loopctl-mcp-server 2.2.0 → 2.23.0

package/index.js

@@ -139,9 +139,12 @@ function toContent(result) {
 /**
  * Compact variant for list endpoints — strips acceptance_criteria and
  * description (use get_story for full details). Keeps all other fields.
- * Enforces a max page size to prevent MCP response token overflow.
+ * A modest DEFAULT page size keeps unprompted responses small, but an explicit
+ * `limit` is honored up to the server's max (500) so story enumeration paginates
+ * honestly instead of silently capping at 20 and skipping rows on offset advance.
  */
-const MAX_PAGE_SIZE = 20;
+const DEFAULT_STORY_PAGE_SIZE = 20;
+const SERVER_MAX_STORY_PAGE_SIZE = 500;
 
 function toContentCompact(result) {
   if (result && result.error === true) return toContent(result);
@@ -175,8 +178,12 @@ async function getTenant() {
   return toContent(result);
 }
 
-async function listProjects() {
-  const result = await apiCall("GET", "/api/v1/projects");
+async function listProjects({ page, page_size } = {}) {
+  const params = new URLSearchParams();
+  if (page != null) params.set("page", String(page));
+  if (page_size != null) params.set("page_size", String(page_size));
+  const query = params.toString() ? `?${params}` : "";
+  const result = await apiCall("GET", `/api/v1/projects${query}`);
   return toContent(result);
 }
 
@@ -367,7 +374,10 @@ async function listStories({ project_id, agent_status, verified_status, epic_id,
   if (agent_status) params.set("agent_status", agent_status);
   if (verified_status) params.set("verified_status", verified_status);
   if (epic_id) params.set("epic_id", epic_id);
-  params.set("limit", String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE)));
+  params.set(
+    "limit",
+    String(Math.min(limit ?? DEFAULT_STORY_PAGE_SIZE, SERVER_MAX_STORY_PAGE_SIZE)),
+  );
   if (offset != null) params.set("offset", String(offset));
   if (include_token_totals) params.set("include_token_totals", "true");
 
@@ -375,9 +385,13 @@ async function listStories({ project_id, agent_status, verified_status, epic_id,
   return toContentCompact(result);
 }
 
-async function listReadyStories({ project_id, limit }) {
+async function listReadyStories({ project_id, page, page_size }) {
+  // /stories/ready paginates by page/page_size — the old `limit` param was
+  // silently ignored by the server, capping callers at the first page.
   const params = new URLSearchParams({ project_id });
-  params.set("limit", String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE)));
+  if (page != null) params.set("page", String(page));
+  if (page_size != null)
+    params.set("page_size", String(Math.min(page_size, SERVER_MAX_STORY_PAGE_SIZE)));
 
   const result = await apiCall("GET", `/api/v1/stories/ready?${params}`);
   return toContentCompact(result);
@@ -550,14 +564,20 @@ async function getCostSummary({ project_id, breakdown }) {
   return toContent(result);
 }
 
-async function getStoryTokenUsage({ story_id }) {
-  const result = await apiCall("GET", `/api/v1/stories/${story_id}/token-usage`);
+async function getStoryTokenUsage({ story_id, page, page_size }) {
+  const params = new URLSearchParams();
+  if (page != null) params.set("page", String(page));
+  if (page_size != null) params.set("page_size", String(page_size));
+  const query = params.toString() ? `?${params}` : "";
+  const result = await apiCall("GET", `/api/v1/stories/${story_id}/token-usage${query}`);
   return toContent(result);
 }
 
-async function getCostAnomalies({ project_id }) {
+async function getCostAnomalies({ project_id, page, page_size }) {
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
+  if (page != null) params.set("page", String(page));
+  if (page_size != null) params.set("page_size", String(page_size));
 
   const query = params.toString() ? `?${params}` : "";
   const result = await apiCall("GET", `/api/v1/cost-anomalies${query}`);
@@ -579,31 +599,214 @@ async function setTokenBudget({ scope_type, scope_id, budget_millicents, alert_t
 
 // --- Knowledge Wiki Tools (agent key) ---
 
-async function knowledgeIndex({ project_id, story_id }) {
+async function knowledgeIndex({ project_id, story_id, category, tags, match, offset, limit, fields }) {
+  if (project_id && !UUID_RE.test(project_id)) {
+    return {
+      content: [{ type: "text", text: "Error: project_id must be a canonical UUID (8-4-4-4-12 hex)." }],
+      isError: true,
+    };
+  }
   const basePath = project_id
     ? `/api/v1/projects/${project_id}/knowledge/index`
     : "/api/v1/knowledge/index";
   const params = new URLSearchParams();
   if (story_id) params.set("story_id", story_id);
+  if (category) params.set("category", category);
+  if (tags) params.set("tags", tags);
+  if (match) params.set("match", match);
+  if (offset != null) params.set("offset", String(offset));
+  if (limit != null) params.set("limit", String(limit));
+  if (fields) params.set("fields", Array.isArray(fields) ? fields.join(",") : fields);
   const qs = params.toString();
   const path = qs ? `${basePath}?${qs}` : basePath;
   const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
 
-async function knowledgeSearch({ q, project_id, story_id, category, tags, mode, limit }) {
-  const params = new URLSearchParams({ q });
+async function knowledgeStats({ project_id }) {
+  if (project_id && !UUID_RE.test(project_id)) {
+    return {
+      content: [{ type: "text", text: "Error: project_id must be a canonical UUID (8-4-4-4-12 hex)." }],
+      isError: true,
+    };
+  }
+  const path = project_id
+    ? `/api/v1/projects/${project_id}/knowledge/stats`
+    : "/api/v1/knowledge/stats";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeGraph({ article_id, depth, project_id }) {
+  const params = new URLSearchParams();
+  params.set("article_id", article_id);
+  if (depth != null) params.set("depth", String(depth));
+  if (project_id) params.set("project_id", project_id);
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/graph?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function knowledgeSuggestLinks({ article_id, limit, threshold }) {
+  const params = new URLSearchParams();
+  if (limit != null) params.set("limit", String(limit));
+  if (threshold != null) params.set("threshold", String(threshold));
+  const qs = params.toString();
+  const base = `/api/v1/knowledge/articles/${article_id}/suggested_links`;
+  const result = await apiCall(
+    "GET",
+    qs ? `${base}?${qs}` : base,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function knowledgeDistantPairs({ min_distance, max_distance, bridge_path, limit, offset }) {
+  const params = new URLSearchParams();
+  if (min_distance != null) params.set("min_distance", String(min_distance));
+  if (max_distance != null) params.set("max_distance", String(max_distance));
+  if (bridge_path === true) params.set("bridge_path", "true");
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  const qs = params.toString();
+  const path = qs ? `/api/v1/knowledge/pairs?${qs}` : "/api/v1/knowledge/pairs";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeNovelty({ ideas, texts, prior_tag }) {
+  // Accept either shape (#169): `ideas` (strings or objects) or `texts` (strings).
+  const body = {};
+  if (ideas !== undefined) body.ideas = ideas;
+  if (texts !== undefined) body.texts = texts;
+  if (prior_tag) body.prior_tag = prior_tag;
+  const result = await apiCall("POST", "/api/v1/knowledge/novelty", body, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeRandomWalk({ start_id, length }) {
+  const params = new URLSearchParams();
+  params.set("start_id", start_id);
+  if (length != null) params.set("length", String(length));
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/walk?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function knowledgeCount({
+  project_id,
+  category,
+  status,
+  tags,
+  match,
+  source_type,
+  source_id,
+  idempotency_key,
+}) {
+  const params = new URLSearchParams();
+  if (project_id) params.set("project_id", project_id);
+  if (category) params.set("category", category);
+  if (status) params.set("status", status);
+  if (tags) params.set("tags", tags);
+  if (match) params.set("match", match);
+  if (source_type) params.set("source_type", source_type);
+  if (source_id) params.set("source_id", source_id);
+  if (idempotency_key) params.set("idempotency_key", idempotency_key);
+  const qs = params.toString();
+  const path = qs ? `/api/v1/knowledge/count?${qs}` : "/api/v1/knowledge/count";
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  return toContent(result);
+}
+
+async function knowledgeFacets({
+  project_id,
+  category,
+  status,
+  tags,
+  match,
+  tag_prefix,
+  limit,
+}) {
+  const params = new URLSearchParams();
+  params.set("group_by", "tag");
+  if (project_id) params.set("project_id", project_id);
+  if (category) params.set("category", category);
+  if (status) params.set("status", status);
+  if (tags) params.set("tags", tags);
+  if (match) params.set("match", match);
+  if (tag_prefix) params.set("tag_prefix", tag_prefix);
+  if (limit != null) params.set("limit", String(limit));
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/facets?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function knowledgeSearch({ q, project_id, story_id, category, tags, match, mode, limit, offset }) {
+  const params = new URLSearchParams();
+  if (q != null && q !== "") params.set("q", q);
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
   if (category) params.set("category", category);
   if (tags) params.set("tags", tags);
+  if (match) params.set("match", match);
   if (mode) params.set("mode", mode);
   if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
 
   const result = await apiCall("GET", `/api/v1/knowledge/search?${params}`, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
 
+async function knowledgeList({
+  project_id,
+  category,
+  status,
+  tags,
+  match,
+  source_type,
+  source_id,
+  idempotency_key,
+  limit,
+  offset,
+  include_body,
+}) {
+  const params = new URLSearchParams();
+  if (project_id) params.set("project_id", project_id);
+  if (category) params.set("category", category);
+  if (status) params.set("status", status);
+  if (tags) params.set("tags", tags);
+  if (match) params.set("match", match);
+  if (source_type) params.set("source_type", source_type);
+  if (source_id) params.set("source_id", source_id);
+  if (idempotency_key) params.set("idempotency_key", idempotency_key);
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  // Body-less summary by default (safe to enumerate large pages); opt into full
+  // bodies (byte-budget bounded server-side) with include_body: true.
+  if (include_body === true) params.set("include_body", "true");
+
+  const result = await apiCall(
+    "GET",
+    `/api/v1/articles?${params}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function knowledgeGet({ article_id, project_id, story_id }) {
   const params = new URLSearchParams();
   if (project_id) params.set("project_id", project_id);
@@ -614,24 +817,63 @@ async function knowledgeGet({ article_id, project_id, story_id }) {
   return toContent(result);
 }
 
-async function knowledgeContext({ query, project_id, story_id, limit, recency_weight }) {
+async function knowledgeContext({
+  query,
+  project_id,
+  story_id,
+  limit,
+  recency_weight,
+  memory_types,
+  agents,
+  conversation_id,
+}) {
   const params = new URLSearchParams({ query });
   if (project_id) params.set("project_id", project_id);
   if (story_id) params.set("story_id", story_id);
   if (limit != null) params.set("limit", String(limit));
   if (recency_weight != null) params.set("recency_weight", String(recency_weight));
+  // Agent-memory scoping (comma-separated lists are OR'd; conversation_id is exact).
+  if (memory_types) params.set("memory_types", Array.isArray(memory_types) ? memory_types.join(",") : memory_types);
+  if (agents) params.set("agents", Array.isArray(agents) ? agents.join(",") : agents);
+  if (conversation_id) params.set("conversation_id", conversation_id);
 
   const result = await apiCall("GET", `/api/v1/knowledge/context?${params}`, null, process.env.LOOPCTL_AGENT_KEY);
   return toContent(result);
 }
 
-async function knowledgeCreate({ title, body, category, tags, project_id }) {
+async function knowledgeCreate({
+  title,
+  body,
+  category,
+  tags,
+  project_id,
+  draft,
+  source_type,
+  source_id,
+  idempotency_key,
+  metadata,
+}) {
   const payload = { title, body };
   if (category) payload.category = category;
   if (tags) payload.tags = tags;
   if (project_id) payload.project_id = project_id;
+  if (source_type) payload.source_type = source_type;
+  if (source_id) payload.source_id = source_id;
+  if (idempotency_key) payload.idempotency_key = idempotency_key;
+  if (metadata) payload.metadata = metadata;
+
+  // Articles publish on create by default for every role (including agent), so a
+  // plain create routes through the agent key and is immediately visible. Pass
+  // draft:true to stage it for later review instead — publish it afterwards with
+  // knowledge_publish.
+  if (draft) payload.draft = true;
 
-  const result = await apiCall("POST", "/api/v1/articles", payload, process.env.LOOPCTL_AGENT_KEY);
+  const result = await apiCall(
+    "POST",
+    "/api/v1/articles",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
   return toContent(result);
 }
 
@@ -649,6 +891,46 @@ async function knowledgeBulkPublish({ article_ids }) {
     { article_ids },
     process.env.LOOPCTL_USER_KEY
   );
+
+  // Partial success returns 200 even when nothing published. Surface a warning
+  // so the agent doesn't treat not_found/errored ids as success.
+  const counts = result?.meta?.counts;
+  if (counts && (counts.not_found > 0 || counts.errored > 0)) {
+    const warning =
+      `WARNING: bulk-publish was partial — published ${counts.published}, ` +
+      `skipped ${counts.skipped}, not_found ${counts.not_found}, errored ${counts.errored} ` +
+      `(of ${counts.requested} requested). Inspect meta.results for per-id outcomes; ` +
+      `not_found/errored ids were NOT published.`;
+    return {
+      content: [{ type: "text", text: warning }, ...toContent(result).content],
+    };
+  }
+
+  return toContent(result);
+}
+
+async function knowledgeBulkUnpublish({ article_ids }) {
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/bulk-unpublish",
+    { article_ids },
+    process.env.LOOPCTL_USER_KEY
+  );
+
+  // Partial success returns 200 even when nothing unpublished. Surface a warning
+  // so the agent doesn't treat not_found/errored ids as success.
+  const counts = result?.meta?.counts;
+  if (counts && (counts.not_found > 0 || counts.errored > 0)) {
+    const warning =
+      `WARNING: bulk-unpublish was partial — unpublished ${counts.unpublished}, ` +
+      `skipped ${counts.skipped}, not_found ${counts.not_found}, errored ${counts.errored} ` +
+      `(of ${counts.requested} requested). Inspect meta.results for per-id outcomes; ` +
+      `not_found/errored ids were NOT unpublished.`;
+    return {
+      content: [{ type: "text", text: warning }, ...toContent(result).content],
+    };
+  }
+
   return toContent(result);
 }
 
@@ -682,12 +964,68 @@ async function knowledgeDelete({ article_id }) {
   return toContent(result);
 }
 
+async function knowledgeBulkDelete({
+  article_ids,
+  source_type,
+  source_id,
+  tag,
+  confirm,
+  dry_run,
+  hard,
+  token,
+  confirm_hash,
+}) {
+  const payload = {};
+  if (article_ids) payload.article_ids = article_ids;
+  if (source_type) payload.source_type = source_type;
+  if (source_id) payload.source_id = source_id;
+  if (tag) payload.tag = tag;
+  if (confirm) payload.confirm = confirm;
+  // US-27.12: dry-run preview + irreversible hard delete via a single-use frozen
+  // token. dry_run=true mutates nothing (returns meta.would_affect; for the hard
+  // path a single-use meta.token); hard=true + token performs the FK-correct
+  // IRREVERSIBLE delete over the frozen id-set. Oversized selectors echo
+  // meta.confirm_hash for re-confirm-on-drift instead of a token.
+  if (dry_run) payload.dry_run = true;
+  if (hard) payload.hard = true;
+  if (token) payload.token = token;
+  if (confirm_hash) payload.confirm_hash = confirm_hash;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/bulk-delete",
+    payload,
+    process.env.LOOPCTL_USER_KEY,
+  );
+
+  // Partial success returns 200 even when some/none archived — surface a warning
+  // so the agent doesn't treat not_found/errored, or a nothing-archived run, as
+  // success.
+  const counts = result?.meta?.counts;
+  if (
+    counts &&
+    (counts.not_found > 0 ||
+      counts.errored > 0 ||
+      (counts.archived === 0 && counts.requested > 0))
+  ) {
+    const warning =
+      `WARNING: bulk-delete was partial — archived ${counts.archived}, ` +
+      `skipped ${counts.skipped}, not_found ${counts.not_found}, errored ${counts.errored} ` +
+      `(of ${counts.requested}). Inspect meta.results; not_found/errored ids were NOT archived.`;
+    return {
+      content: [{ type: "text", text: warning }, ...toContent(result).content],
+    };
+  }
+
+  return toContent(result);
+}
+
 async function knowledgeDrafts({ limit, offset, project_id }) {
   const params = new URLSearchParams();
-  params.set(
-    "limit",
-    String(Math.min(limit ?? MAX_PAGE_SIZE, MAX_PAGE_SIZE))
-  );
+  // Pass `limit` through verbatim (like knowledge_list/index/search) so the
+  // server honors it up to its max page size and returns 400 above it — rather
+  // than silently clamping client-side, which would truncate draft enumeration.
+  if (limit != null) params.set("limit", String(limit));
   if (offset != null) params.set("offset", String(offset));
   if (project_id) params.set("project_id", project_id);
   const path = `/api/v1/knowledge/drafts?${params.toString()}`;
@@ -709,24 +1047,28 @@ async function knowledgeLint({ project_id, stale_days, min_coverage, max_per_cat
   return toContent(result);
 }
 
-async function knowledgeIngest({ url, content, source_type, project_id }) {
+async function knowledgeIngest({ url, content, source_type, project_id, publish }) {
   const body = { source_type };
   if (url) body.url = url;
   if (content) body.content = content;
   if (project_id) body.project_id = project_id;
+  if (publish) body.publish = true;
   const result = await apiCall("POST", "/api/v1/knowledge/ingest", body, process.env.LOOPCTL_ORCH_KEY);
   return toContent(result);
 }
 
-async function knowledgeIngestBatch({ items, project_id }) {
-  // If a batch-level project_id is supplied, apply it as a default to every
-  // item that doesn't already set its own.
+async function knowledgeIngestBatch({ items, project_id, publish }) {
+  // Apply batch-level project_id / publish as defaults to any item that doesn't
+  // set its own.
   const resolvedItems = Array.isArray(items)
-    ? items.map((item) =>
-        project_id && item && item.project_id == null
-          ? { ...item, project_id }
-          : item
-      )
+    ? items.map((item) => {
+        if (!item) return item;
+        let resolved = item;
+        if (project_id && resolved.project_id == null)
+          resolved = { ...resolved, project_id };
+        if (publish && resolved.publish == null) resolved = { ...resolved, publish: true };
+        return resolved;
+      })
     : items;
 
   const result = await apiCall(
@@ -738,8 +1080,18 @@ async function knowledgeIngestBatch({ items, project_id }) {
   return toContent(result);
 }
 
-async function knowledgeIngestionJobs() {
-  const result = await apiCall("GET", "/api/v1/knowledge/ingestion-jobs", null, process.env.LOOPCTL_ORCH_KEY);
+async function knowledgeIngestionJobs({ limit, offset, since_days } = {}) {
+  const params = new URLSearchParams();
+  if (limit != null) params.set("limit", String(limit));
+  if (offset != null) params.set("offset", String(offset));
+  if (since_days != null) params.set("since_days", String(since_days));
+  const query = params.toString() ? `?${params}` : "";
+  const result = await apiCall(
+    "GET",
+    `/api/v1/knowledge/ingestion-jobs${query}`,
+    null,
+    process.env.LOOPCTL_ORCH_KEY,
+  );
   return toContent(result);
 }
 
@@ -852,12 +1204,18 @@ async function knowledgeExport({ project_id }) {
     ? `/api/v1/projects/${project_id}/knowledge/export`
     : "/api/v1/knowledge/export";
   const baseUrl = getBaseUrl();
-  const downloadCmd = `curl -H "Authorization: Bearer $LOOPCTL_ORCH_KEY" "${baseUrl}${basePath}" -o knowledge-export.zip`;
+  // The export endpoint is role:user — use LOOPCTL_USER_KEY. (LOOPCTL_ORCH_KEY is
+  // orchestrator role, which is BELOW user in the hierarchy and would 403.) The
+  // endpoint streams a gzipped tar (`application/gzip`), so save it as `.tar.gz`.
+  const downloadCmd = `curl -H "Authorization: Bearer $LOOPCTL_USER_KEY" "${baseUrl}${basePath}" -o knowledge-export.tar.gz`;
   return {
     content: [{
       type: "text",
       text: JSON.stringify({
-        message: "Knowledge export produces a ZIP file. Use the curl command below to download it directly.",
+        message:
+          "Knowledge export streams a bounded-memory gzipped tar (.tar.gz). Use the curl " +
+          "command below to download it directly. Requires a user-role key " +
+          "(LOOPCTL_USER_KEY); extract with `tar -xzf knowledge-export.tar.gz`.",
         command: downloadCmd,
         endpoint: `${baseUrl}${basePath}`,
       }, null, 2),
@@ -865,6 +1223,136 @@ async function knowledgeExport({ project_id }) {
   };
 }
 
+// --- OKF (Open Knowledge Format) interchange ---
+
+// Guard a user-supplied absolute filesystem path against pseudo-filesystems.
+function assertSafeAbsolutePath(nodePath, p, label) {
+  if (!nodePath.isAbsolute(p)) {
+    return `${label} must be an absolute path (got '${p}').`;
+  }
+  const blocked = ["/proc", "/dev", "/sys"];
+  if (blocked.some((b) => p === b || p.startsWith(b + "/"))) {
+    return `${label} refused: '${p}' targets a pseudo-filesystem path.`;
+  }
+  return null;
+}
+
+async function knowledgeOkfExport({ project_id, out_dir }) {
+  const basePath = project_id
+    ? `/api/v1/projects/${project_id}/knowledge/okf/export`
+    : "/api/v1/knowledge/okf/export";
+
+  const result = await apiCall(
+    "GET",
+    `${basePath}?format=json`,
+    null,
+    process.env.LOOPCTL_USER_KEY,
+  );
+
+  if (result.error) return toContent(result);
+
+  const bundle = result.data || result;
+  const files = bundle.files || {};
+  const meta = bundle.meta || {};
+
+  if (!out_dir) {
+    return toContent({ meta, file_count: Object.keys(files).length, files });
+  }
+
+  const nodePath = await import("node:path");
+  const pathErr = assertSafeAbsolutePath(nodePath, out_dir, "out_dir");
+  if (pathErr) {
+    return { content: [{ type: "text", text: `Error: ${pathErr}` }], isError: true };
+  }
+  // Normalize so `..`/trailing-slash can't defeat the per-file fence below.
+  const root = nodePath.resolve(out_dir);
+
+  const fs = await import("node:fs/promises");
+  let written = 0;
+  for (const [rel, content] of Object.entries(files)) {
+    // Keep writes inside root even if a server-supplied path is adversarial.
+    const dest = nodePath.resolve(root, rel);
+    if (dest !== root && !dest.startsWith(root + nodePath.sep)) continue;
+    await fs.mkdir(nodePath.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, content, "utf8");
+    written += 1;
+  }
+
+  return toContent({ meta, out_dir: root, written });
+}
+
+async function knowledgeOkfImport({ bundle_dir, project_id, merge, dry_run }) {
+  const nodePath = await import("node:path");
+  const pathErr = assertSafeAbsolutePath(nodePath, bundle_dir, "bundle_dir");
+  if (pathErr) {
+    return { content: [{ type: "text", text: `Error: ${pathErr}` }], isError: true };
+  }
+
+  const fs = await import("node:fs/promises");
+
+  let stat;
+  try {
+    stat = await fs.stat(bundle_dir);
+  } catch {
+    return { content: [{ type: "text", text: `Error: bundle_dir '${bundle_dir}' not found.` }], isError: true };
+  }
+  if (!stat.isDirectory()) {
+    return { content: [{ type: "text", text: `Error: bundle_dir '${bundle_dir}' is not a directory.` }], isError: true };
+  }
+
+  // Kept in step with the server-side caps in okf_controller.ex.
+  const MAX_FILES = 10_000;
+  const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
+  const files = {};
+  let totalBytes = 0;
+
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = nodePath.join(dir, entry.name);
+      // Never traverse or read through symlinks (escape out of bundle_dir).
+      if (entry.isSymbolicLink()) {
+        continue;
+      } else if (entry.isDirectory()) {
+        await walk(abs);
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
+        if (Object.keys(files).length >= MAX_FILES) {
+          throw new Error(`bundle exceeds ${MAX_FILES} files`);
+        }
+        const content = await fs.readFile(abs, "utf8");
+        totalBytes += Buffer.byteLength(content, "utf8");
+        if (totalBytes > MAX_TOTAL_BYTES) {
+          throw new Error("bundle exceeds 25 MiB total");
+        }
+        files[nodePath.relative(bundle_dir, abs).split(nodePath.sep).join("/")] = content;
+      }
+    }
+  }
+
+  try {
+    await walk(bundle_dir);
+  } catch (e) {
+    return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+  }
+
+  if (Object.keys(files).length === 0) {
+    return { content: [{ type: "text", text: `Error: no .md files found under '${bundle_dir}'.` }], isError: true };
+  }
+
+  const payload = { files };
+  if (project_id) payload.project_id = project_id;
+  if (merge != null) payload.merge = merge;
+  if (dry_run != null) payload.dry_run = dry_run;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/knowledge/okf/import",
+    payload,
+    process.env.LOOPCTL_USER_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Discovery Tools ---
 
 async function listRoutes() {
@@ -934,10 +1422,15 @@ const TOOLS = [
   },
   {
     name: "list_projects",
-    description: "List all projects in the current tenant.",
+    description:
+      "List projects in the current tenant. Paginated (page/page_size); advance " +
+      "`page` to enumerate all projects. Response includes pagination meta.",
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: { type: "integer", description: "Items per page (default 20)." },
+      },
       required: [],
     },
   },
@@ -1098,8 +1591,8 @@ const TOOLS = [
     description:
       "List stories for a project, optionally filtered by agent_status, verified_status, or epic_id. " +
       "Returns compact results (no acceptance_criteria/description) — use get_story for full details. " +
-      "Max 20 per page. Use offset to paginate (response includes total_count). " +
-      "Filter by epic_id or agent_status to reduce result size.",
+      "Defaults to 20 per page; pass `limit` up to 500 to page larger. Use offset to paginate " +
+      "(response includes total_count). Filter by epic_id or agent_status to reduce result size.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1122,7 +1615,7 @@ const TOOLS = [
         },
         limit: {
           type: "integer",
-          description: "Maximum number of stories to return.",
+          description: "Maximum number of stories to return (default 20, max 500).",
         },
         offset: {
           type: "integer",
@@ -1141,7 +1634,8 @@ const TOOLS = [
     description:
       "List stories that are ready to be worked on (contracted, dependencies met). " +
       "Returns compact results — use get_story for full details. " +
-      "Max 20 per page. Response includes total_count for pagination.",
+      "Paginated (page/page_size); advance `page` to enumerate all ready stories. " +
+      "Response includes total_count.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1149,9 +1643,10 @@ const TOOLS = [
           type: "string",
           description: "The UUID of the project.",
         },
-        limit: {
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: {
           type: "integer",
-          description: "Maximum number of stories to return.",
+          description: "Stories per page (default 100, max 500).",
         },
       },
       required: ["project_id"],
@@ -1496,7 +1991,9 @@ const TOOLS = [
   },
   {
     name: "get_story_token_usage",
-    description: "Get token usage records for a single story.",
+    description:
+      "Get token usage records for a single story. Paginated (page/page_size); " +
+      "advance `page` to enumerate all records.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1504,6 +2001,8 @@ const TOOLS = [
           type: "string",
           description: "The UUID of the story.",
         },
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: { type: "integer", description: "Records per page (default 20)." },
       },
       required: ["story_id"],
     },
@@ -1512,7 +2011,8 @@ const TOOLS = [
     name: "get_cost_anomalies",
     description:
       "Get cost anomaly alerts — stories or agents that exceed expected token budgets. " +
-      "Optionally filter by project.",
+      "Optionally filter by project. Paginated (page/page_size); advance `page` to " +
+      "enumerate all anomalies.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1520,6 +2020,8 @@ const TOOLS = [
           type: "string",
           description: "Optional: filter anomalies to a specific project UUID.",
         },
+        page: { type: "integer", description: "Page number (default 1)." },
+        page_size: { type: "integer", description: "Anomalies per page (default 20)." },
       },
       required: [],
     },
@@ -1560,7 +2062,13 @@ const TOOLS = [
   {
     name: "knowledge_index",
     description:
-      "Load the knowledge wiki catalog at session start. Returns article metadata grouped by category. " +
+      "Browse/paginate the knowledge wiki catalog. Returns LIGHTWEIGHT article metadata grouped by " +
+      "category — by default only id, title, category per article (NOT full metadata). " +
+      "Honors category/tags filters and offset/limit pagination with deterministic ordering, so " +
+      "every article is reachable (meta.categories reports per-category counts over the whole " +
+      "filtered set; meta.has_more/meta.truncated signal more pages). Use `fields` to control the " +
+      "projection (request tags/status/updated_at explicitly; id and category are always included) " +
+      "to keep the payload small on large catalogs. " +
       "Pass story_id when working on a loopctl story so reads attribute correctly.",
     inputSchema: {
       type: "object",
@@ -1575,51 +2083,395 @@ const TOOLS = [
           format: "uuid",
           description: "Optional: loopctl story UUID for attribution tracking.",
         },
+        category: {
+          type: "string",
+          enum: ["pattern", "convention", "decision", "finding", "reference"],
+          description: "Optional: filter to a single category. Rejected (400) if unknown.",
+        },
+        tags: {
+          type: "string",
+          description: "Optional: comma-separated tags; matches articles carrying ANY of them.",
+        },
+        match: {
+          type: "string",
+          enum: ["any", "all"],
+          description: "Optional: tag match mode — 'any' (default, OR) or 'all' (AND, every tag).",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: rows to skip for pagination (default 0).",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: max articles per page (default 1000, max 1000).",
+        },
+        fields: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["id", "title", "category", "tags", "status", "updated_at"],
+          },
+          description:
+            "Optional: projection of article fields to return. Default: id, title, category. `id` is always included.",
+        },
       },
       required: [],
     },
   },
   {
-    name: "knowledge_search",
+    name: "knowledge_list",
     description:
-      "Search the knowledge wiki by topic. Returns snippets. " +
-      "Pass story_id when working on a loopctl story so reads attribute correctly.",
+      "List articles (id, title, category, status, tags, source_type, source_id, " +
+      "idempotency_key, timestamps), filtered and paginated. **Body-less summary by default** " +
+      "— the right tool to enumerate, dedup, or repair at scale (safe to page up to limit=1000). " +
+      "Pass `include_body: true` to also return the full `body`, in which case the server bounds " +
+      "the page by a ~5 MB serialized-body budget and returns meta.next_offset/has_more/" +
+      "byte_truncated for continuation (for a single full body use knowledge_get; for the relevant " +
+      "bodies use knowledge_context; for a bulk content dump use knowledge_export). Unlike " +
+      "knowledge_search (ranked, PUBLISHED-only, lags writes while embeddings index) and " +
+      "knowledge_index (id/title/category only), this is the LAG-FREE, ALL-STATUS read of the DB " +
+      "of record (draft, published, archived, superseded visible). Use for idempotency/existence " +
+      "checks: filter by `tags`, `source_type`+`source_id`, or `idempotency_key` and read " +
+      "`meta.total_count` (exact) to answer \"does an article for X already exist?\" reliably " +
+      "right after a write. Paginate via offset/limit.",
     inputSchema: {
       type: "object",
       properties: {
-        q: {
-          type: "string",
-          description: "Search query string.",
-        },
         project_id: {
           type: "string",
           format: "uuid",
-          description: "Optional: scope search to a specific project UUID.",
+          description: "Optional: scope to a project UUID.",
         },
-        story_id: {
+        category: {
           type: "string",
-          format: "uuid",
-          description: "Optional: loopctl story UUID for attribution tracking.",
+          description: "Optional: filter by category.",
         },
-        category: {
+        status: {
           type: "string",
-          description: "Optional: filter results by category.",
+          description: "Optional: filter by status (draft, published, archived, superseded).",
         },
         tags: {
           type: "string",
-          description: "Optional: comma-separated tags to filter by.",
+          description: "Optional: comma-separated tags; matches articles carrying ANY of them.",
         },
-        mode: {
+        match: {
           type: "string",
-          enum: ["keyword", "semantic", "combined"],
-          description: "Optional: search mode (keyword, semantic, or combined).",
+          enum: ["any", "all"],
+          description: "Optional: tag match mode — 'any' (default, OR) or 'all' (AND, every tag).",
+        },
+        source_type: {
+          type: "string",
+          description: "Optional: filter by source_type.",
+        },
+        source_id: {
+          type: "string",
+          description: "Optional: filter by source_id (a malformed id matches nothing).",
+        },
+        idempotency_key: {
+          type: "string",
+          description:
+            "Optional: filter by exact idempotency_key — the lag-free existence check for a " +
+            "prior capture.",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: rows to skip for pagination (default 0).",
         },
         limit: {
           type: "integer",
-          description: "Optional: maximum number of results to return.",
+          description:
+            "Optional: max articles per page (default 20, max 1000). A limit above " +
+            "the max is rejected with 400 — not silently clamped — so paging by offset " +
+            "over meta.total_count enumerates the complete set without skipping rows.",
         },
+        include_body: {
+          type: "boolean",
+          description:
+            "Optional (default false): when true, include the full article `body`. The page is " +
+            "then bounded by a ~5 MB serialized-body budget (it may return fewer than `limit` " +
+            "rows); continue via meta.next_offset while meta.has_more is true. Leave false to " +
+            "enumerate metadata cheaply at scale.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_stats",
+    description:
+      "Get aggregate article counts for the wiki without pulling any article metadata. " +
+      "Returns { total, by_category, by_status } via cheap COUNT(*) GROUP BY. This is the " +
+      "right tool to answer \"how many articles are in this project?\" — knowledge_index " +
+      "pages article metadata and knowledge_search's total_count is query-dependent. Counts " +
+      "span all statuses (draft/published/archived/superseded); see by_status for the split. " +
+      "Note: `total` is NOT the same as knowledge_index's meta.total_count (which counts only " +
+      "published) — they differ whenever drafts/archived exist.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description:
+            "Optional: scope counts to a project (counts both tenant-wide and project-specific articles).",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_count",
+    description:
+      "Count articles matching filters WITHOUT returning any rows. Accepts the same filters " +
+      "as knowledge_list (category, status, tags, match, source_type, source_id, " +
+      "idempotency_key, project_id). With tags + match:'all' it counts articles carrying ALL " +
+      "the tags; add status:'published' to answer \"how many PUBLISHED articles tagged both X " +
+      "and Y\". Removes the need to paginate rows just to count. Returns { count }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", format: "uuid", description: "Optional: scope to a project UUID." },
+        category: { type: "string", description: "Optional: filter by category." },
+        status: { type: "string", description: "Optional: filter by status." },
+        tags: { type: "string", description: "Optional: comma-separated tags." },
+        match: {
+          type: "string",
+          enum: ["any", "all"],
+          description: "Tag match mode: 'any' (default, OR) or 'all' (AND — carries every tag).",
+        },
+        source_type: { type: "string", description: "Optional: filter by source_type." },
+        source_id: { type: "string", description: "Optional: filter by source_id." },
+        idempotency_key: { type: "string", description: "Optional: filter by idempotency_key." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_facets",
+    description:
+      "Count articles grouped by each distinct tag, over the filtered set, WITHOUT returning " +
+      "rows. Returns { data: { tag: count }, meta: { distinct_count, truncated } }. " +
+      "meta.distinct_count is the TRUE number of distinct tags (independent of limit); " +
+      "meta.truncated flags when limit capped the rows. Each `count` is the number of distinct " +
+      "articles carrying that tag. Pass tag_prefix to restrict to a tag family (e.g. 'book-') " +
+      "so you get the DISTINCT count of that family (how many distinct books) plus per-member " +
+      "totals — without dragging tens of thousands of rows through context. Honors the same " +
+      "filters as knowledge_count (status, tags, match). Cost: unnests tags over the whole " +
+      "filtered set; on large tenants narrow with tag_prefix/category/status/project_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: { type: "string", format: "uuid", description: "Optional: scope to a project UUID." },
+        category: { type: "string", description: "Optional: filter by category." },
+        status: { type: "string", description: "Optional: filter by status." },
+        tags: { type: "string", description: "Optional: comma-separated tags." },
+        match: {
+          type: "string",
+          enum: ["any", "all"],
+          description: "Tag match mode: 'any' (default, OR) or 'all' (AND).",
+        },
+        tag_prefix: {
+          type: "string",
+          description: "Optional: only tags starting with this literal prefix (e.g. 'book-').",
+        },
+        limit: { type: "integer", description: "Optional: max distinct tags in the result (default all, max 1000; values above 1000 are rejected with 400)." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_graph",
+    description:
+      "Traverse the published article-link graph outward from an article, up to `depth` hops " +
+      "(1–3, default 1). BIDIRECTIONAL (follows links regardless of source/target direction) and " +
+      "cycle-safe (no node twice). Returns { nodes: [{id,title,category,depth}], edges: " +
+      "[{source_article_id,target_article_id,relationship_type}], truncated, node_count }. Bounded " +
+      "to 100 nodes / 500 edges (truncated:true when hit). Use to explore how a piece of knowledge " +
+      "connects (relates_to/derived_from/contradicts/supersedes) beyond the 1-hop links in " +
+      "knowledge_context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          format: "uuid",
+          description: "Starting article UUID (required).",
+        },
+        depth: {
+          type: "integer",
+          minimum: 1,
+          maximum: 3,
+          description: "Hops to traverse (1–3, default 1). Out of range → 400.",
+        },
+        project_id: { type: "string", format: "uuid", description: "Optional: project UUID." },
+      },
+      required: ["article_id"],
+    },
+  },
+  {
+    name: "knowledge_suggest_links",
+    description:
+      "Suggest ranked typed-link CANDIDATES for an article by embedding similarity — " +
+      "READ-ONLY, creates nothing. Excludes the article itself and any already-linked " +
+      "article (either direction, any relationship type); only embedded published articles. " +
+      "Returns { data: [{id, title, category, similarity_score}] } highest-similarity first. " +
+      "Review them and create the one you want as a TYPED link (relates_to/derived_from/" +
+      "contradicts/supersedes) — unlike the auto-linker which only makes ambient relates_to. " +
+      "Optional: threshold (cosine floor 0–1, default 0.5), limit (default 5).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_id: {
+          type: "string",
+          format: "uuid",
+          description: "The article to suggest links for (required).",
+        },
+        limit: { type: "integer", description: "Max candidates (default 5)." },
+        threshold: {
+          type: "number",
+          minimum: 0,
+          maximum: 1,
+          description: "Cosine similarity floor (default 0.5).",
+        },
+      },
+      required: ["article_id"],
+    },
+  },
+  {
+    name: "knowledge_distant_pairs",
+    description:
+      "Find distant-but-bridgeable article pairs in the optimal-novelty embedding band " +
+      "(cosine distance min..max, default 0.3–0.7) — the creative sweet spot (neither banal " +
+      "nor nonsense). Returns { data: [{a, b, distance}], meta:{count} }. With bridge_path:true, " +
+      "only pairs also connected in the link graph (≤2 hops) are returned. Samples up to 1000 " +
+      "embedded published articles; paginate via limit/offset. For computational-creativity " +
+      "ideation (remote-associates generator).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        min_distance: { type: "number", description: "Lower cosine-distance bound (default 0.3)." },
+        max_distance: { type: "number", description: "Upper cosine-distance bound (default 0.7)." },
+        bridge_path: { type: "boolean", description: "Require a ≤2-hop graph path (default false)." },
+        limit: { type: "integer", description: "Max pairs (default 20, max 100)." },
+        offset: { type: "integer", description: "Pairs to skip." },
       },
-      required: ["q"],
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_novelty",
+    description:
+      "Score the NOVELTY of ideas: each idea's text is embedded and compared to the nearest " +
+      "prior proposal, returning novelty_score = cosine distance (0 = identical to existing " +
+      "work, higher = more novel, up to 2.0; null when the idea text is blank, no priors " +
+      "exist, or embedding fails). Priors default to published articles tagged 'proposal' " +
+      "(override with prior_tag). Provide the ideas as EITHER `texts` (a list of strings) " +
+      "OR `ideas` (a list of strings or objects {text|title/spark/thesis,...}); all forms " +
+      "are accepted. " +
+      "Returns { data: [{...idea, novelty_score}], meta: { prior_count } }. Use to rerank " +
+      "generated ideas by novelty × value and avoid repeating prior work.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ideas: {
+          type: "array",
+          description:
+            "Ideas to score (≤50). Each is a string, or an object whose embed text is " +
+            "`text` (else title/spark/thesis are joined).",
+          items: { type: ["string", "object"] },
+        },
+        texts: {
+          type: "array",
+          description: "Alternative to `ideas`: a list of idea strings (the #152 AC shape).",
+          items: { type: "string" },
+        },
+        prior_tag: {
+          type: "string",
+          description: "Tag identifying prior proposals to compare against (default 'proposal').",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_random_walk",
+    description:
+      "Random walk through the link graph from a starting article (up to `length` published " +
+      "nodes, no cycles, stops at a dead end). Surfaces unexpected connections for creative " +
+      "incubation. Returns { data: [{id,title,category}], meta:{count} } in walk order.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        start_id: { type: "string", format: "uuid", description: "Starting article UUID (required)." },
+        length: { type: "integer", description: "Walk steps (default 4, max 25)." },
+      },
+      required: ["start_id"],
+    },
+  },
+  {
+    name: "knowledge_search",
+    description:
+      "Search the knowledge wiki by topic. Returns snippets. Ranked, and returns PUBLISHED " +
+      "articles only; it LAGS writes by minutes while embeddings index. Do NOT use it for " +
+      "existence/idempotency/dedup checks ('already captured?') — a freshly-written article will " +
+      "false-negative. Use knowledge_list (lag-free, all-status, exact meta.total_count) for that. " +
+      "q is optional when tags and/or category are supplied: in that list mode it returns the " +
+      "COMPLETE filtered set (no relevance ranking) paginated via offset/limit over " +
+      "meta.total_count, so you can enumerate every article carrying a tag/category. " +
+      "IMPORTANT: meta.total_count is mode-dependent — read meta.total_count_scope to know what " +
+      "it counts: keyword_matches (stop-word-filtered tsquery matches; 'the' matches ~nothing), " +
+      "ranked_corpus (semantic ranks all EMBEDDED published articles — that embedded set's size, " +
+      "not a match count, and <= the published count), merged_candidates (combined: deduped UNION of " +
+      "a keyword and a semantic sub-search, each capped at 100, so up to ~200), or filtered_set " +
+      "(list mode: the full set). Do NOT use a relevance-mode total_count to size the wiki — use " +
+      "list mode or knowledge_stats. " +
+      "Pass story_id when working on a loopctl story so reads attribute correctly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        q: {
+          type: "string",
+          description:
+            "Search query string. Optional when tags/category are supplied (enumeration mode).",
+        },
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: scope search to a specific project UUID.",
+        },
+        story_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: loopctl story UUID for attribution tracking.",
+        },
+        category: {
+          type: "string",
+          description: "Optional: filter results by category.",
+        },
+        tags: {
+          type: "string",
+          description: "Optional: comma-separated tags to filter by.",
+        },
+        match: {
+          type: "string",
+          enum: ["any", "all"],
+          description: "Optional: tag match mode — 'any' (default, OR) or 'all' (AND, every tag).",
+        },
+        mode: {
+          type: "string",
+          enum: ["keyword", "semantic", "combined"],
+          description: "Optional: search mode (keyword, semantic, or combined).",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: maximum number of results to return.",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: results to skip for pagination (default 0).",
+        },
+      },
+      required: [],
     },
   },
   {
@@ -1653,7 +2505,11 @@ const TOOLS = [
     name: "knowledge_context",
     description:
       "Get ranked full articles for a task query. Returns best knowledge with linked references. " +
-      "Pass story_id when working on a loopctl story so reads attribute correctly.",
+      "Pass story_id when working on a loopctl story so reads attribute correctly. For agent " +
+      "memory, scope to a memory_type/agent/conversation via the memory_types/agents/" +
+      "conversation_id filters (articles whose metadata carries those keys). NOTE (#163): for " +
+      "an agent key, another agent's private/owner memories are never returned (results AND " +
+      "linked refs) regardless of the agents= filter — visibility is enforced, not advisory.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1681,6 +2537,20 @@ const TOOLS = [
           minimum: 0,
           maximum: 1,
         },
+        memory_types: {
+          type: "string",
+          description:
+            "Optional agent-memory scope: comma-separated memory_types (OR) — " +
+            "observation|finding|summary|decision|question|task.",
+        },
+        agents: {
+          type: "string",
+          description: "Optional agent-memory scope: comma-separated agent_ids (OR).",
+        },
+        conversation_id: {
+          type: "string",
+          description: "Optional agent-memory scope: exact conversation_id.",
+        },
       },
       required: ["query"],
     },
@@ -1689,7 +2559,15 @@ const TOOLS = [
     name: "knowledge_create",
     description:
       "Create a new knowledge article. Use to file findings, document patterns, or record decisions " +
-      "discovered during implementation.",
+      "discovered during implementation. Articles are PUBLISHED IMMEDIATELY by default and are visible " +
+      "to agents (search/index/context) right away — no separate publish step is needed. Pass " +
+      "draft: true to stage the article for later review instead; the response `note` says which " +
+      "outcome occurred, and a draft can be published afterwards with knowledge_publish. " +
+      "Concurrency-safe: if a create races/retries against an " +
+      "existing article with the same title AND an identical body (ignoring surrounding whitespace), the " +
+      "server returns that existing article idempotently (HTTP 200) instead of a 422. A same-title create " +
+      "with a DIFFERENT body returns 409 title_conflict — do not retry; choose a different title or PATCH " +
+      "the existing article.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1714,6 +2592,47 @@ const TOOLS = [
           type: "string",
           description: "Optional: associate the article with a project UUID.",
         },
+        draft: {
+          type: "boolean",
+          description:
+            "Optional: stage as a draft instead of publishing on create (default false → " +
+            "published immediately). Publish later with knowledge_publish.",
+        },
+        idempotency_key: {
+          type: "string",
+          description:
+            "Optional: stable per-article key for idempotent capture (max 255). Re-creating " +
+            "with the same key is a no-op that returns a reference to the existing article " +
+            "(deduplicated; id only, not its body) instead of a partial duplicate. Use a " +
+            "HIGH-ENTROPY value (e.g. a content hash) — it is a per-tenant lookup key, not a " +
+            "secret, so a guessable key lets another agent in your tenant probe which keys " +
+            "exist. Distinct from source_type/source_id (which mark a shared source).",
+        },
+        metadata: {
+          type: "object",
+          description:
+            "Optional: extensible JSONB. Set the agent-memory keys to file this article as a " +
+            "scoped agent memory: `memory_type` (observation/finding/summary/decision/question/" +
+            "task) and `visibility` (shared | private | owner). TRUST MODEL (#163): for an " +
+            "agent key, `metadata.agent_id` is stamped server-side from your verified key " +
+            "identity — do NOT set it (any value you pass is overridden); `private`/`owner` " +
+            "memories are then readable only by you (other agents get 404/exclusion across all " +
+            "knowledge reads), while `shared` (the default) is visible tenant-wide. An agent " +
+            "key with no agent identity gets 403 agent_identity_required when writing memory " +
+            "metadata. Higher roles may attribute on behalf of others.",
+        },
+        source_type: {
+          type: "string",
+          description:
+            "Optional: advisory provenance for the originating source (e.g. 'web_article', " +
+            "'newsletter'). Shared across articles from the same source; not an idempotency key.",
+        },
+        source_id: {
+          type: "string",
+          description:
+            "Optional: UUID of the originating source entity (shared across articles from " +
+            "that source). Pair with source_type.",
+        },
       },
       required: ["title", "body"],
     },
@@ -1738,19 +2657,48 @@ const TOOLS = [
   {
     name: "knowledge_bulk_publish",
     description:
-      "Atomically publish up to 100 draft articles in a single call. " +
-      "REQUIRES LOOPCTL_USER_KEY to be set in the MCP server env (user role — " +
-      "orchestrator role is NOT sufficient for this destructive operation). " +
-      "All articles must be drafts belonging to the tenant; if any fail validation, " +
-      "the entire operation rolls back.",
+      "Publish draft articles, partial-success style. REQUIRES LOOPCTL_USER_KEY " +
+      "(user role — orchestrator is NOT sufficient). Every valid draft is published; " +
+      "each other id gets a per-id outcome instead of failing the whole call: " +
+      "published, skipped (already published — idempotent — or archived/superseded), " +
+      "not_found, or errored. Duplicate ids are de-duplicated and there is NO 100-id " +
+      "cap (larger requests are auto-chunked server-side). The response's meta.count " +
+      "is the number actually published; meta.counts has the full breakdown and " +
+      "meta.results is the per-id list in request order. Safe to retry — already " +
+      "published ids are skipped, not errored.",
     inputSchema: {
       type: "object",
       properties: {
         article_ids: {
           type: "array",
           items: { type: "string" },
-          description: "List of draft article UUIDs to publish (max 100).",
-          maxItems: 100,
+          description:
+            "Article UUIDs to publish. Any length (auto-chunked); duplicates ignored.",
+        },
+      },
+      required: ["article_ids"],
+    },
+  },
+  {
+    name: "knowledge_bulk_unpublish",
+    description:
+      "Unpublish (published → draft) articles in bulk, partial-success style — the mirror " +
+      "of knowledge_bulk_publish, for cleanup passes. REQUIRES LOOPCTL_USER_KEY (user role). " +
+      "Every currently-published id is reverted to draft; each other id gets a per-id outcome: " +
+      "unpublished, skipped (already draft — idempotent — or archived/superseded), not_found, " +
+      "or errored. Duplicate ids de-duplicated; no 100-id cap (auto-chunked server-side, " +
+      "bounded to 5000/call). meta.count = number actually unpublished; meta.counts has the " +
+      "full breakdown; meta.results is the per-id list in request order. Safe to retry — " +
+      "already-draft ids are skipped, not errored. Articles are NOT deleted (re-publish with " +
+      "knowledge_bulk_publish); to archive/soft-delete use knowledge_bulk_delete.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_ids: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Article UUIDs to unpublish. Any length (auto-chunked); duplicates ignored.",
         },
       },
       required: ["article_ids"],
@@ -1810,20 +2758,92 @@ const TOOLS = [
       required: ["article_id"],
     },
   },
+  {
+    name: "knowledge_bulk_delete",
+    description:
+      "Bulk archive (default, reversible) or IRREVERSIBLE hard-delete of articles by selector. " +
+      "REQUIRES LOOPCTL_USER_KEY (user role — orchestrator is NOT sufficient). Provide EXACTLY ONE " +
+      "selector: article_ids (explicit list), source_type + source_id (every active article from " +
+      "that source), or tag + confirm:true (every active article carrying the tag — high blast " +
+      "radius, so confirm:true is required). " +
+      "DEFAULT (soft archive): rows move to archived, never dropped; set-based + idempotent; " +
+      "meta.count = archived, meta.counts/meta.results give the breakdown. " +
+      "DRY-RUN: dry_run:true mutates NOTHING and returns meta.would_affect (and, for hard, a " +
+      "single-use meta.token / for oversized selectors a meta.confirm_hash). " +
+      "HARD DELETE (irreversible): first dry_run with hard:true to get a token, then call again " +
+      "with hard:true + that token to FK-correctly delete the FROZEN id-set (links removed first, " +
+      "access events cascade). The token is single-use and TTL-bounded. Bounded to 5000 per call.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        article_ids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Explicit article UUIDs (selector 1).",
+        },
+        source_type: {
+          type: "string",
+          description: "With source_id: every active article from this source (selector 2).",
+        },
+        source_id: {
+          type: "string",
+          description: "With source_type: the source entity UUID (selector 2).",
+        },
+        tag: {
+          type: "string",
+          description:
+            "Every active article carrying this tag (selector 3). Requires confirm:true.",
+        },
+        confirm: {
+          type: "boolean",
+          description: "Required (true) when selecting by tag — guards the high blast radius.",
+        },
+        dry_run: {
+          type: "boolean",
+          description:
+            "Preview only — mutate nothing. Returns meta.would_affect; with hard:true also a " +
+            "single-use meta.token (or meta.confirm_hash for oversized selectors).",
+        },
+        hard: {
+          type: "boolean",
+          description:
+            "IRREVERSIBLE hard delete (vs default reversible archive). Run dry_run first to get a " +
+            "token, then pass hard:true + token.",
+        },
+        token: {
+          type: "string",
+          description:
+            "The single-use frozen-set token from a `dry_run:true, hard:true` preview. Required " +
+            "for the hard delete.",
+        },
+        confirm_hash: {
+          type: "string",
+          description:
+            "For an oversized hard-delete selector (no token): the meta.confirm_hash from the " +
+            "dry-run, echoed back to re-confirm the id-set hasn't drifted.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "knowledge_drafts",
     description:
       "List draft (unpublished) knowledge articles. Requires orchestrator role. " +
-      "Returns paginated drafts with total_count in meta. Max 20 per page.",
+      "Returns paginated drafts with total_count in meta. Paginate via offset/limit " +
+      "(limit honored up to 1000; a limit above the max is rejected with 400, not " +
+      "silently clamped).",
     inputSchema: {
       type: "object",
       properties: {
         limit: {
           type: "integer",
-          description: "Max drafts per page. Default 20, hard max 20.",
+          description:
+            "Max drafts per page (default 20, max 1000). A limit above the max is " +
+            "rejected with 400 — not silently clamped — so offset pagination stays complete.",
           default: 20,
           minimum: 1,
-          maximum: 20,
+          maximum: 1000,
         },
         offset: {
           type: "integer",
@@ -1878,8 +2898,9 @@ const TOOLS = [
   {
     name: "knowledge_export",
     description:
-      "Export all knowledge articles as a ZIP archive. Because ZIP binary cannot be returned as MCP content, " +
-      "this tool returns a curl command you can run directly to download the archive.",
+      "Export all knowledge articles as an OKF v0.1 bundle — gzipped tar archive, unbounded, bounded-memory streaming, " +
+      "fail-closed (no partial bundles). Because binary cannot be returned as MCP content, this tool returns a curl command. " +
+      "Optional: ?format=json for buffered in-memory JSON (capped at export_max_buffered_export_articles, 413 over cap).",
     inputSchema: {
       type: "object",
       properties: {
@@ -1887,10 +2908,71 @@ const TOOLS = [
           type: "string",
           description: "Optional: scope export to a specific project UUID.",
         },
+        format: {
+          type: "string",
+          enum: ["tar.gz", "json"],
+          description: "Optional: tar.gz (default, unbounded streaming) or json (buffered, capped).",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "knowledge_okf_export",
+    description:
+      "Export the knowledge wiki as a portable OKF (Open Knowledge Format) v0.1 bundle — a tree of " +
+      "markdown files with YAML frontmatter. Requires LOOPCTL_USER_KEY. If out_dir is given, the bundle " +
+      "is written there (one .md file per concept, plus index.md/log.md) and a summary is returned; " +
+      "otherwise the bundle is returned inline as {files, meta}.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: scope the export to a project (includes tenant-wide articles too).",
+        },
+        out_dir: {
+          type: "string",
+          description:
+            "Optional: absolute path of a directory to write the bundle into. When omitted, the " +
+            "bundle is returned inline.",
+        },
       },
       required: [],
     },
   },
+  {
+    name: "knowledge_okf_import",
+    description:
+      "Import an OKF (Open Knowledge Format) v0.1 bundle from a local directory into the wiki. " +
+      "Requires LOOPCTL_USER_KEY. Reserved files (index.md/log.md) are skipped; each concept is created, " +
+      "or (with merge=true, the default) updated in place when it matches an existing article. Unknown " +
+      "frontmatter types/keys are tolerated and preserved. Returns a per-file import report.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        bundle_dir: {
+          type: "string",
+          description: "Absolute path of the OKF bundle directory to read .md files from.",
+        },
+        project_id: {
+          type: "string",
+          format: "uuid",
+          description: "Optional: assign imported articles to a project.",
+        },
+        merge: {
+          type: "boolean",
+          description: "Update existing articles instead of skipping them (default true).",
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Validate and plan only; write nothing (default false).",
+        },
+      },
+      required: ["bundle_dir"],
+    },
+  },
 
   // Knowledge Ingestion Tools
   {
@@ -1898,7 +2980,9 @@ const TOOLS = [
     description:
       "Submit a URL or raw content for knowledge extraction. " +
       "Enqueues an Oban job that fetches the content (if URL), extracts knowledge articles via LLM, " +
-      "and inserts them as draft articles. Requires orchestrator role.",
+      "and inserts them. Extracted articles are DRAFTS by default (lower-trust LLM output, staged " +
+      "for review) — unlike knowledge_create which publishes by default. Pass publish:true to " +
+      "publish them on extraction. Requires orchestrator role.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1918,6 +3002,11 @@ const TOOLS = [
           type: "string",
           description: "Optional: scope extracted articles to a specific project UUID.",
         },
+        publish: {
+          type: "boolean",
+          description:
+            "Optional: publish extracted articles immediately instead of staging them as drafts (default false).",
+        },
       },
       required: ["source_type"],
     },
@@ -1956,6 +3045,11 @@ const TOOLS = [
                 type: "string",
                 description: "Optional: scope the item to a specific project UUID.",
               },
+              publish: {
+                type: "boolean",
+                description:
+                  "Optional: publish this item's extracted articles immediately (default false → draft).",
+              },
               metadata: {
                 type: "object",
                 description: "Optional metadata map.",
@@ -1968,6 +3062,10 @@ const TOOLS = [
           type: "string",
           description: "Optional batch-level default project UUID applied to items that don't specify their own.",
         },
+        publish: {
+          type: "boolean",
+          description: "Optional batch-level default publish flag applied to items that don't specify their own.",
+        },
       },
       required: ["items"],
     },
@@ -1975,11 +3073,20 @@ const TOOLS = [
   {
     name: "knowledge_ingestion_jobs",
     description:
-      "List recent content ingestion jobs for the current tenant. " +
-      "Returns jobs from the last 7 days, max 50 results. Requires orchestrator role.",
+      "List content ingestion jobs for the current tenant, newest first. " +
+      "Paginated (limit/offset over the full history; advance `offset` by `meta.limit` " +
+      "to enumerate to completeness). Optional `since_days` narrows to a recent window. " +
+      "Requires orchestrator role.",
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        limit: { type: "integer", description: "Jobs per page (default 20)." },
+        offset: { type: "integer", description: "Rows to skip (default 0)." },
+        since_days: {
+          type: "integer",
+          description: "Optional: only jobs from the last N days (default: all history).",
+        },
+      },
       required: [],
     },
   },
@@ -2298,9 +3405,36 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_index":
       return await knowledgeIndex(args);
 
+    case "knowledge_stats":
+      return await knowledgeStats(args);
+
+    case "knowledge_count":
+      return await knowledgeCount(args);
+
+    case "knowledge_facets":
+      return await knowledgeFacets(args);
+
+    case "knowledge_graph":
+      return await knowledgeGraph(args);
+
+    case "knowledge_suggest_links":
+      return await knowledgeSuggestLinks(args);
+
+    case "knowledge_distant_pairs":
+      return await knowledgeDistantPairs(args);
+
+    case "knowledge_novelty":
+      return await knowledgeNovelty(args);
+
+    case "knowledge_random_walk":
+      return await knowledgeRandomWalk(args);
+
     case "knowledge_search":
       return await knowledgeSearch(args);
 
+    case "knowledge_list":
+      return await knowledgeList(args);
+
     case "knowledge_get":
       return await knowledgeGet(args);
 
@@ -2317,6 +3451,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_bulk_publish":
       return await knowledgeBulkPublish(args);
 
+    case "knowledge_bulk_unpublish":
+      return await knowledgeBulkUnpublish(args);
+
     case "knowledge_unpublish":
       return await knowledgeUnpublish(args);
 
@@ -2326,6 +3463,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_delete":
       return await knowledgeDelete(args);
 
+    case "knowledge_bulk_delete":
+      return await knowledgeBulkDelete(args);
+
     case "knowledge_drafts":
       return await knowledgeDrafts(args);
 
@@ -2335,6 +3475,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_export":
       return await knowledgeExport(args);
 
+    case "knowledge_okf_export":
+      return await knowledgeOkfExport(args);
+
+    case "knowledge_okf_import":
+      return await knowledgeOkfImport(args);
+
     // Knowledge Ingestion Tools
     case "knowledge_ingest":
       return await knowledgeIngest(args);