@withone/cli 1.56.1 → 1.57.1

package/dist/index.js

@@ -35,7 +35,7 @@ import {
 } from "./chunk-QCXFSOTS.js";
 import {
   memSqlCommand
-} from "./chunk-KAF5SVJS.js";
+} from "./chunk-GKAIRI4Y.js";
 import {
   collectIdentityKeys,
   countRecords,
@@ -66,7 +66,7 @@ import {
   writeDraftProfile,
   writePageToMemory,
   writeProfile
-} from "./chunk-XWTV7FA3.js";
+} from "./chunk-YTM6HJKA.js";
 import {
   getByDotPath
 } from "./chunk-44CV5IMX.js";
@@ -100,7 +100,7 @@ import {
   listBackendPlugins,
   loadBackendFromConfig,
   updateRecord
-} from "./chunk-VH46MAE4.js";
+} from "./chunk-IMU2X3ZV.js";
 import {
   DEFAULT_MEMORY_CONFIG,
   defaultSearchableText,
@@ -3109,6 +3109,391 @@ async function platformsCommand(options) {
 // src/commands/actions.ts
 import * as p6 from "@clack/prompts";
 import pc8 from "picocolors";
+
+// src/lib/knowledge-sections.ts
+var DEFAULT_WHOLE_DOC_THRESHOLD = 8e3;
+var DEFAULT_DIGEST_BUDGET = 8e3;
+var DEFAULT_SECTION_CAP = 6e3;
+var HEADING_RE = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+var FENCE_RE = /^\s*(```|~~~)/;
+function slugify(heading) {
+  return heading.toLowerCase().replace(/`/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "section";
+}
+function parseSections(markdown) {
+  const normalized = markdown.replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n");
+  const prefaceLines = [];
+  const blocks = [];
+  let inFence = false;
+  let fenceMarker = "";
+  for (const line of lines) {
+    const fence = FENCE_RE.exec(line);
+    if (fence) {
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = fence[1];
+      } else if (fence[1] === fenceMarker) {
+        inFence = false;
+      }
+    }
+    const m = !inFence ? HEADING_RE.exec(line) : null;
+    if (m) {
+      blocks.push({ level: m[1].length, heading: m[2].trim(), lines: [line] });
+      continue;
+    }
+    if (blocks.length === 0) prefaceLines.push(line);
+    else blocks[blocks.length - 1].lines.push(line);
+  }
+  const usedIds = /* @__PURE__ */ new Set();
+  const nodes = blocks.map((b) => {
+    const base = slugify(b.heading);
+    let id = base;
+    for (let n = 2; usedIds.has(id); n++) id = `${base}-${n}`;
+    usedIds.add(id);
+    return {
+      id,
+      heading: b.heading,
+      level: b.level,
+      text: b.lines.join("\n"),
+      chars: 0,
+      tier: classifyHeading(b.heading),
+      children: []
+    };
+  });
+  const root = [];
+  const stack = [];
+  let title = "";
+  let titleNode = null;
+  for (const node of nodes) {
+    while (stack.length && stack[stack.length - 1].level >= node.level) stack.pop();
+    if (stack.length) stack[stack.length - 1].children.push(node);
+    else root.push(node);
+    stack.push(node);
+  }
+  if (root.length && nodes[0].level === 1 && root[0] === nodes[0]) {
+    titleNode = root.shift();
+    title = titleNode.heading;
+    root.unshift(...titleNode.children);
+    titleNode.children = [];
+  }
+  let preface = prefaceLines.join("\n").trim();
+  if (titleNode) {
+    const own = titleNode.text.split("\n").slice(1).join("\n").trim();
+    if (own) preface = preface ? `${preface}
+
+${own}` : own;
+  }
+  const measure = (n) => {
+    n.chars = n.text.length + n.children.reduce((sum, c) => sum + measure(c), 0);
+    return n.chars;
+  };
+  root.forEach(measure);
+  return { title, preface, sections: root, chars: normalized.length };
+}
+function sectionText(section) {
+  const parts = [section.text, ...section.children.map(sectionText)];
+  return parts.join("\n").replace(/\n+$/, "");
+}
+function flattenSections(sections) {
+  const out = [];
+  const walk = (list) => {
+    for (const s of list) {
+      out.push(s);
+      walk(s.children);
+    }
+  };
+  walk(sections);
+  return out;
+}
+function canonicalHeading(heading) {
+  return heading.toLowerCase().replace(/\s*\([^)]*\)\s*$/, "").replace(/[`*_]/g, "").replace(/\s+/g, " ").trim();
+}
+var ESSENTIAL_EXACT = /* @__PURE__ */ new Set([
+  "prerequisites",
+  "method",
+  "url",
+  "endpoint",
+  "headers",
+  "description",
+  "enforcement rules",
+  "valid examples",
+  "invalid examples",
+  "request body",
+  "sample request",
+  "gotchas",
+  "error handling",
+  "graphql operation",
+  "graphql arguments",
+  "request variables",
+  "variables",
+  "path parameters",
+  "query parameters",
+  "parameters",
+  "arguments"
+]);
+var ESSENTIAL_PREFIX = ["required "];
+function classifyHeading(heading) {
+  const c = canonicalHeading(heading);
+  if (ESSENTIAL_EXACT.has(c)) return "essential";
+  if (ESSENTIAL_PREFIX.some((p10) => c.startsWith(p10))) return "essential";
+  return "deferred";
+}
+function deferredPriority(heading) {
+  const c = canonicalHeading(heading);
+  if (c.startsWith("optional ")) return 0;
+  if (c === "behavior" || c === "behaviour") return 1;
+  if (c === "notes") return 2;
+  if (c === "example usage" || c.startsWith("example")) return 3;
+  if (c === "response fields") return 5;
+  if (c === "response" || c.startsWith("success response") || c.startsWith("error response")) return 6;
+  return 4;
+}
+function truncateText(text5, cap, id) {
+  const cut = text5.slice(0, cap);
+  const nl = cut.lastIndexOf("\n");
+  const head = nl > cap * 0.5 ? cut.slice(0, nl) : cut;
+  const remaining = text5.length - head.length;
+  return `${head}
+
+_[truncated \u2014 ${remaining.toLocaleString("en-US")} more chars. Load the full section with --section ${id}]_`;
+}
+function buildDigest(doc, opts = {}) {
+  const wholeThreshold = opts.wholeDocThreshold ?? DEFAULT_WHOLE_DOC_THRESHOLD;
+  const budget = opts.budget ?? DEFAULT_DIGEST_BUDGET;
+  const cap = opts.sectionCap ?? DEFAULT_SECTION_CAP;
+  const flat = flattenSections(doc.sections);
+  const whole = () => ({
+    markdown: renderWhole(doc),
+    truncated: false,
+    sections: flat.map((s) => summary(s, true)),
+    omitted: 0,
+    omittedChars: 0
+  });
+  if (flat.length === 0 || doc.chars <= wholeThreshold) return whole();
+  const decisions = /* @__PURE__ */ new Map();
+  let used = doc.title ? doc.title.length + 4 : 0;
+  used += doc.preface.length;
+  const hasEssentialDescendant = (n) => n.children.some((c) => c.tier === "essential" || hasEssentialDescendant(c));
+  const walk = (list) => {
+    for (const node of list) {
+      if (node.tier === "essential" || node.level >= 3 && hasEssentialDescendant(node)) {
+        const own = node.text;
+        if (own.length > cap) {
+          const render = truncateText(own, cap, node.id);
+          decisions.set(node.id, { node, included: "partial", render });
+          used += render.length;
+        } else {
+          decisions.set(node.id, { node, included: true, render: own });
+          used += own.length;
+        }
+        walk(node.children);
+      } else {
+        decisions.set(node.id, { node, included: false, render: "" });
+        for (const c of flattenSections(node.children)) decisions.set(c.id, { node: c, included: false, render: "" });
+      }
+    }
+  };
+  walk(doc.sections);
+  const candidates = flat.filter((s) => decisions.get(s.id)?.included === false).filter((s) => s.level >= 2).filter((s) => {
+    const parent = parentOf(doc.sections, s);
+    return !parent || decisions.get(parent.id)?.included !== false;
+  }).sort((a, b) => deferredPriority(a.heading) - deferredPriority(b.heading) || a.chars - b.chars);
+  for (const s of candidates) {
+    if (used + s.chars > budget) continue;
+    for (const n of [s, ...flattenSections(s.children)]) {
+      decisions.set(n.id, { node: n, included: true, render: n.text });
+    }
+    used += s.chars;
+  }
+  const allIn = flat.every((s) => decisions.get(s.id)?.included === true);
+  if (allIn) return whole();
+  const out = [];
+  if (doc.title) out.push(`# ${doc.title}`);
+  if (doc.preface) out.push(doc.preface);
+  for (const s of flat) {
+    const d = decisions.get(s.id);
+    if (d.included !== false) out.push(d.render.replace(/\n+$/, ""));
+  }
+  const sections = flat.map((s) => summary(s, decisions.get(s.id).included));
+  const topOmitted = flat.filter((s) => {
+    if (decisions.get(s.id).included !== false) return false;
+    const parent = parentOf(doc.sections, s);
+    return !parent || decisions.get(parent.id).included !== false;
+  });
+  const omittedChars = topOmitted.reduce((sum, s) => sum + s.chars, 0) + flat.filter((s) => decisions.get(s.id).included === "partial").reduce((sum, s) => sum + (s.text.length - decisions.get(s.id).render.length), 0);
+  return {
+    markdown: out.join("\n\n"),
+    truncated: true,
+    sections,
+    omitted: topOmitted.length + flat.filter((s) => decisions.get(s.id).included === "partial").length,
+    omittedChars: Math.max(0, omittedChars)
+  };
+}
+function summary(s, included) {
+  return { id: s.id, heading: s.heading, level: s.level, chars: s.chars, included };
+}
+function parentOf(roots, target) {
+  const find = (list, parent) => {
+    for (const n of list) {
+      if (n === target) return parent;
+      const r = find(n.children, n);
+      if (r !== void 0) return r;
+    }
+    return void 0;
+  };
+  return find(roots, null) ?? null;
+}
+function renderWhole(doc) {
+  const out = [];
+  if (doc.title) out.push(`# ${doc.title}`);
+  if (doc.preface) out.push(doc.preface);
+  for (const s of doc.sections) out.push(sectionText(s));
+  return out.join("\n\n");
+}
+var DEFAULT_TOC_MAX_ENTRIES = 60;
+function collapseSections(sections, max = DEFAULT_TOC_MAX_ENTRIES) {
+  if (sections.length <= max) return { sections, collapsed: false };
+  const firstH1 = sections.findIndex((s) => s.level === 1);
+  const canonEnd = firstH1 === -1 ? sections.length : firstH1;
+  for (const depth of [3, 2]) {
+    const keep = (s, i) => i < canonEnd ? s.level <= depth : s.level <= 1;
+    const count = sections.filter(keep).length;
+    if (count > max && depth !== 2) continue;
+    const out = [];
+    let owner = null;
+    sections.forEach((s, i) => {
+      if (keep(s, i)) {
+        owner = { ...s };
+        out.push(owner);
+      } else if (owner) {
+        owner.children = (owner.children ?? 0) + 1;
+      }
+    });
+    return { sections: out, collapsed: true };
+  }
+  return { sections, collapsed: false };
+}
+function omittedSections(digest, max = DEFAULT_TOC_MAX_ENTRIES) {
+  return collapseSections(digest.sections.filter((s) => s.included !== true), max);
+}
+function renderDigestNotice(digest, platform, actionId) {
+  if (!digest.truncated) return "";
+  const topMost = digest.sections.filter((s, idx) => {
+    if (s.included === true) return false;
+    for (let i = idx - 1; i >= 0; i--) {
+      const prev = digest.sections[i];
+      if (prev.level < s.level) return prev.included !== false;
+    }
+    return true;
+  });
+  const names = topMost.map((s) => {
+    if (s.included === "partial") return `${s.heading} (partial)`;
+    if (s.level === 1) return `${s.heading} (appendix)`;
+    return s.heading;
+  });
+  const base = `one --agent actions knowledge ${platform} ${actionId}`;
+  const MAX_NAMES = 12;
+  const shown = names.slice(0, MAX_NAMES);
+  const rest = names.length - shown.length;
+  const nameList = rest > 0 ? `${shown.join(", ")}, and ${rest} more (see --toc)` : shown.join(", ");
+  return [
+    "---",
+    `**This is a digest, not the full document.** ${topMost.length} section${topMost.length === 1 ? "" : "s"} omitted (${digest.omittedChars.toLocaleString("en-US")} chars): ${nameList}.`,
+    `Load one or more by name or id:  ${base} --section "${topMost[0]?.heading ?? "Response"}"`,
+    `Load everything:                  ${base} --full`
+  ].join("\n");
+}
+function renderDigestBanner(digest) {
+  if (!digest.truncated) return "";
+  return `> **Digest.** ${digest.omitted} section${digest.omitted === 1 ? "" : "s"} (${digest.omittedChars.toLocaleString("en-US")} chars) omitted: response shapes, reference schemas, or worked examples. The notice at the end names them and shows how to load them; the JSON \`sections\` array marks them included:false.`;
+}
+var ALIASES = {
+  response: (c) => c === "response",
+  responses: (c) => c === "response",
+  "response fields": (c) => c === "response fields",
+  fields: (c) => c === "response fields",
+  optional: (c) => c.startsWith("optional "),
+  required: (c) => c.startsWith("required "),
+  examples: (c) => c === "example usage" || c === "examples",
+  example: (c) => c === "example usage" || c === "examples",
+  errors: (c) => c.startsWith("error response") || c === "error handling",
+  success: (c) => c.startsWith("success response"),
+  body: (c) => c === "request body" || c.endsWith("request body fields"),
+  query: (c) => c.endsWith("query parameters"),
+  path: (c) => c.endsWith("path parameters"),
+  notes: (c) => c === "notes",
+  behavior: (c) => c === "behavior" || c === "behaviour",
+  gotchas: (c) => c === "gotchas"
+};
+function normalizeQuery(q) {
+  return q.trim().replace(/^["'`]+|["'`]+$/g, "").toLowerCase().replace(/\s+/g, " ");
+}
+function findSections(doc, query) {
+  const flat = flattenSections(doc.sections);
+  const q = normalizeQuery(query);
+  const qSlug = slugify(q);
+  const miss = (reason, candidates) => ({
+    ok: false,
+    reason,
+    query,
+    candidates: candidates.map((s) => summary(s, false))
+  });
+  if (!q) return miss("not-found", flat);
+  const exact = flat.filter(
+    (s) => s.id === qSlug || canonicalHeading(s.heading) === q || s.heading.toLowerCase() === q
+  );
+  if (exact.length) return { ok: true, sections: exact };
+  const alias = ALIASES[q];
+  if (alias) {
+    const hits = flat.filter((s) => alias(canonicalHeading(s.heading)));
+    if (hits.length) return { ok: true, sections: dropNested(hits) };
+  }
+  const byPrefix = flat.filter(
+    (s) => s.id.startsWith(qSlug) || canonicalHeading(s.heading).startsWith(q)
+  );
+  if (byPrefix.length === 1) return { ok: true, sections: byPrefix };
+  if (byPrefix.length > 1) {
+    const sameCanon = new Set(byPrefix.map((s) => canonicalHeading(s.heading).replace(/\s*\d.*$/, "")));
+    if (sameCanon.size === 1) return { ok: true, sections: dropNested(byPrefix) };
+    return miss("ambiguous", byPrefix);
+  }
+  const bySubstring = flat.filter(
+    (s) => s.id.includes(qSlug) || canonicalHeading(s.heading).includes(q)
+  );
+  if (bySubstring.length === 1) return { ok: true, sections: bySubstring };
+  if (bySubstring.length > 1) return miss("ambiguous", bySubstring);
+  return miss("not-found", flat);
+}
+function dropNested(hits) {
+  const inside = /* @__PURE__ */ new Set();
+  for (const h of hits) for (const c of flattenSections(h.children)) inside.add(c.id);
+  return hits.filter((h) => !inside.has(h.id));
+}
+function selectSections(doc, names) {
+  const picked = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    const r = findSections(doc, name);
+    if (!r.ok) return r;
+    for (const s of dropNested(r.sections)) {
+      if (!seen.has(s.id)) {
+        seen.add(s.id);
+        picked.push(s);
+      }
+    }
+  }
+  const order = new Map(flattenSections(doc.sections).map((s, i) => [s.id, i]));
+  const final = dropNested(picked).sort((a, b) => order.get(a.id) - order.get(b.id));
+  const parts = [doc.title ? `# ${doc.title}` : "", ...final.map(sectionText)].filter(Boolean);
+  return { ok: true, sections: final, markdown: parts.join("\n\n") };
+}
+function parseSectionFlag(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  return raw.flatMap((v) => v.split(",")).map((v) => v.trim()).filter(Boolean);
+}
+
+// src/commands/actions.ts
 function getConfig() {
   const apiKey = getApiKey();
   if (!apiKey) {
@@ -3306,8 +3691,90 @@ async function actionsKnowledgeCommand(platform, actionId, options) {
       knowledge: details.knowledge || "No knowledge was found",
       method: details.method || "No method was found"
     };
+    const doc = parseSections(knowledgeData.knowledge);
+    const sectionNames = parseSectionFlag(options.section);
+    const wantFull = options.full === true || sectionNames.some((n) => n.toLowerCase() === "all");
+    const base = `one --agent actions knowledge ${platform} ${actionId}`;
+    const fullToc = flattenSections(doc.sections).map((s) => ({ id: s.id, heading: s.heading, level: s.level, chars: s.chars }));
+    if (options.toc) {
+      if (isAgentMode()) {
+        json({
+          title: doc.title,
+          method: knowledgeData.method,
+          chars: doc.chars,
+          sections: fullToc,
+          more: { section: `${base} --section <id or heading>[,<id or heading>...]`, full: `${base} --full` },
+          _cache: buildCacheMeta(entry, cacheHit)
+        });
+        return;
+      }
+      spinner4.stop("Sections");
+      console.log();
+      for (const t of fullToc) console.log(`${"  ".repeat(Math.max(0, t.level - 1))}${t.heading} ${pc8.dim(`[${t.id}] ${t.chars} chars`)}`);
+      console.log();
+      return;
+    }
+    if (sectionNames.length > 0 && !wantFull) {
+      const picked = selectSections(doc, sectionNames);
+      if (!picked.ok) {
+        const toc = collapseSections(picked.candidates);
+        const list = toc.sections.map((c) => `${"  ".repeat(Math.max(0, c.level - 2))}${c.heading} [${c.id}] (${c.chars} chars${c.children ? `, +${c.children} nested` : ""})`).join("\n");
+        if (isAgentMode()) {
+          json({
+            error: picked.reason === "ambiguous" ? `Section "${picked.query}" matches several sections; pick one by id or full heading.` : `No section named "${picked.query}". Use one of the ids or headings below, or --full.`,
+            query: picked.query,
+            reason: picked.reason,
+            sections: toc.sections.map(({ id, heading, level, chars, children }) => children ? { id, heading, level, chars, children } : { id, heading, level, chars }),
+            ...toc.collapsed ? { sectionsCollapsed: true, sectionCount: picked.candidates.length } : {},
+            hint: `${base} --section <id or heading>`,
+            toc: `${base} --toc`
+          });
+          process.exit(1);
+        }
+        spinner4.stop("Section not found");
+        error(`${picked.reason === "ambiguous" ? "Ambiguous" : "Unknown"} section "${picked.query}". Available:
+${list}`);
+      }
+      if (isAgentMode()) {
+        json({
+          knowledge: picked.markdown,
+          method: knowledgeData.method,
+          title: doc.title,
+          // The requested sections are returned whole; nothing here was cut.
+          truncated: false,
+          requested: sectionNames,
+          // What each name matched — fuzzy and alias matches are visible here.
+          resolved: picked.sections.map((s) => ({ id: s.id, heading: s.heading, chars: s.chars })),
+          sectionCount: fullToc.length,
+          more: {
+            note: "Only the requested sections are included. The digest call listed the others; `--toc` lists all of them.",
+            section: `${base} --section <id or heading>[,<id or heading>...]`,
+            toc: `${base} --toc`,
+            full: `${base} --full`
+          },
+          _cache: buildCacheMeta(entry, cacheHit)
+        });
+        return;
+      }
+      spinner4.stop("Sections loaded");
+      console.log();
+      console.log(picked.markdown);
+      console.log();
+      return;
+    }
+    const digest = buildDigest(
+      doc,
+      isAgentMode() && !wantFull ? {} : { wholeDocThreshold: Number.POSITIVE_INFINITY }
+    );
+    const body = doc.sections.length === 0 ? knowledgeData.knowledge : digest.markdown;
+    const notice = renderDigestNotice(digest, platform, actionId);
+    const banner = renderDigestBanner(digest);
     const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(
-      knowledgeData.knowledge,
+      notice ? `${banner}
+
+${body}
+
+${notice}` : body,
       knowledgeData.method,
       platform,
       actionId
@@ -3316,8 +3783,26 @@ async function actionsKnowledgeCommand(platform, actionId, options) {
       const response = {
         knowledge: knowledgeWithGuidance,
         method: knowledgeData.method,
+        title: doc.title || void 0,
+        truncated: digest.truncated,
         _cache: buildCacheMeta(entry, cacheHit)
       };
+      if (digest.truncated) {
+        const toc = omittedSections(digest);
+        response.omitted = digest.omitted;
+        response.omittedChars = digest.omittedChars;
+        response.sections = toc.sections;
+        if (toc.collapsed) {
+          response.sectionsCollapsed = true;
+          response.sectionCount = digest.sections.length;
+        }
+        response.more = {
+          note: toc.collapsed ? `This is a digest. \`sections\` lists what was omitted, collapsed to ${toc.sections.length} entries (\`children\` counts nested ones); request any by id or heading, or --toc for all ${digest.sections.length} headings.` : "This is a digest. `sections` lists what was omitted; request any by id or heading.",
+          section: `${base} --section <id or heading>[,<id or heading>...]`,
+          toc: `${base} --toc`,
+          full: `${base} --full`
+        };
+      }
       json(response);
       return;
     }
@@ -6746,7 +7231,7 @@ async function syncModel(api, profile, options) {
         updateModelState(platform, model, { status: "failed", pagesProcessed, lastCursor }),
         (async () => {
           try {
-            const { getBackend: getBackend2 } = await import("./runtime-65IPTPVD.js");
+            const { getBackend: getBackend2 } = await import("./runtime-SX36HGBA.js");
             const backend = await getBackend2();
             await Promise.race([
               backend.close(),
@@ -7112,7 +7597,7 @@ async function syncModel(api, profile, options) {
         db.exec(`DROP TABLE IF EXISTS _seen_ids`);
       }
       if (options.toMemory !== false) {
-        const backend = await (await import("./runtime-65IPTPVD.js")).getBackend();
+        const backend = await (await import("./runtime-SX36HGBA.js")).getBackend();
         const type = `${platform}/${model}`;
         const existing = await backend.listKeysByType(type);
         const sourcePrefix = `${type}:`;
@@ -7213,7 +7698,7 @@ async function syncModel(api, profile, options) {
     let statusCounts;
     if (options.toMemory !== false) {
       try {
-        const backend = await (await import("./runtime-65IPTPVD.js")).getBackend();
+        const backend = await (await import("./runtime-SX36HGBA.js")).getBackend();
         const typeName = `${platform}/${model}`;
         const [active, archived] = await Promise.all([
           backend.count(typeName, { status: "active" }),
@@ -8935,7 +9420,7 @@ ${result.total} results`);
   }
 }
 async function syncSqlCommand(platformModel, sql) {
-  const { syncSqlCommand: runSyncSql } = await import("./sql-QIVDWTL3.js");
+  const { syncSqlCommand: runSyncSql } = await import("./sql-SYCWUPNP.js");
   await runSyncSql(platformModel, sql);
 }
 async function syncDeleteCommand(platformModel, options) {
@@ -9013,7 +9498,7 @@ async function syncDeleteCommand(platformModel, options) {
 async function maybeAutoMigrateLegacy(platform, models) {
   const dbSize = getDatabaseSize(platform);
   if (!dbSize || dbSize === "0 B") return;
-  const { getBackend: getBackend2 } = await import("./runtime-65IPTPVD.js");
+  const { getBackend: getBackend2 } = await import("./runtime-SX36HGBA.js");
   const backend = await getBackend2();
   let memoryHasData = false;
   for (const model of models) {
@@ -9029,7 +9514,7 @@ async function maybeAutoMigrateLegacy(platform, models) {
       `  detected legacy .one/sync/data/${platform}.db (${dbSize}) \u2014 auto-migrating into memory before sync.
 `
     );
-    const { memMigrateCommand: memMigrateCommand3 } = await import("./migrate-IJI3BTWL.js");
+    const { memMigrateCommand: memMigrateCommand3 } = await import("./migrate-TACDLGPD.js");
     await memMigrateCommand3({ platform, yes: true });
     return;
   }
@@ -9038,7 +9523,7 @@ async function maybeAutoMigrateLegacy(platform, models) {
     initialValue: true
   });
   if (p7.isCancel(shouldMigrate) || !shouldMigrate) return;
-  const { memMigrateCommand: memMigrateCommand2 } = await import("./migrate-IJI3BTWL.js");
+  const { memMigrateCommand: memMigrateCommand2 } = await import("./migrate-TACDLGPD.js");
   await memMigrateCommand2({ platform, yes: true });
 }
 async function syncSuggestSearchableCommand(platformModel, options = {}) {
@@ -9099,7 +9584,7 @@ async function syncSuggestSearchableCommand(platformModel, options = {}) {
 async function syncListCommand(platform) {
   const profiles = listProfiles(platform);
   const state = await readSyncState();
-  const { getBackend: getBackend2 } = await import("./runtime-65IPTPVD.js");
+  const { getBackend: getBackend2 } = await import("./runtime-SX36HGBA.js");
   const backend = await getBackend2();
   const syncs = await Promise.all(profiles.map(async (p10) => {
     const modelState = state[p10.platform]?.[p10.model];
@@ -9375,7 +9860,7 @@ function registerSyncSubcommands(sync) {
     await syncSqlCommand(platformModel, sql);
   });
   sync.command("schema <platform/model>").description("Inspect the JSON structure of synced records (field paths, types, examples) \u2014 useful before writing `sync sql` queries").action(async (platformModel) => {
-    const { syncSchemaCommand } = await import("./schema-OO4WK5ND.js");
+    const { syncSchemaCommand } = await import("./schema-RJC2WQQ6.js");
     await syncSchemaCommand(platformModel);
   });
   sync.command("delete <platform/model>").description('Delete records from local sync data (e.g. one sync delete notion/pages --id "abc-123")').option("--id <value>", "Delete record by ID").option("--where <conditions>", 'Delete records matching conditions (e.g. "status=archived")').option("--where-sql <predicate>", `Delete using a raw SQL WHERE clause (e.g. "json_extract(data, '$.type') = 'promotion'")`).option("--yes", "Skip confirmation prompt").action(async (platformModel, options) => {
@@ -10833,7 +11318,43 @@ one --agent actions search <platform> "<query>" -t execute
 one --agent actions knowledge <platform> <actionId>
 \`\`\`
 
-Returns full API docs: required fields, validation rules, request structure. **REQUIRED before execute.** The output includes a CLI PARAMETER MAPPING section showing which flags to use.
+Returns the API docs: required fields, validation rules, request structure. **REQUIRED before execute.** The output includes a CLI PARAMETER MAPPING section showing which flags to use.
+
+**In \`--agent\` mode this is a digest, not the whole document.** Large docs (most of their size is response shapes and optional-field tables) are trimmed to the sections needed to build a correct request: method/URL, headers, description, enforcement rules, required and optional parameters, sample request, gotchas, error handling. Everything else is listed in a table of contents so you can pull it on demand:
+
+\`\`\`json
+{
+  "knowledge": "...digest markdown, ends with a notice naming the omitted sections...",
+  "method": "POST",
+  "title": "Create an Issue",
+  "truncated": true,
+  "sections": [
+    { "id": "response", "heading": "Response", "level": 2, "chars": 16483, "included": false },
+    { "id": "response-fields", "heading": "Response Fields", "level": 2, "chars": 3353, "included": false }
+  ],
+  "omitted": 2,
+  "omittedChars": 19836,
+  "more": { "section": "one --agent actions knowledge <platform> <actionId> --section <id>[,<id>...]", "full": "..." }
+}
+\`\`\`
+
+- \`truncated: false\` means you have the whole document \u2014 small docs are never trimmed, and no \`sections\` list is sent.
+- \`sections\` lists only what was omitted. \`included\` is \`false\` or \`"partial"\` (an oversized essential section was cut; its text ends with a truncation marker). Included sections are simply the headings in the markdown.
+- Load more by heading, id, or alias \u2014 several at once, comma-separated or repeated:
+
+\`\`\`bash
+one --agent actions knowledge <platform> <actionId> --section "Response Fields"
+one --agent actions knowledge <platform> <actionId> --section response,optional
+one --agent actions knowledge <platform> <actionId> --full
+\`\`\`
+
+Aliases: \`response\`, \`fields\`, \`optional\`, \`required\`, \`examples\`, \`errors\`, \`success\`, \`body\`, \`query\`, \`path\`, \`notes\`, \`behavior\`, \`gotchas\`. A parent section brings its subsections. Section requests are served from the local cache \u2014 no network call. An unknown name returns an error that lists every available section, so retry with one of those ids.
+
+A \`--section\` response carries \`requested\`, \`resolved\` (the ids each name matched \u2014 alias and prefix matches are visible here), and \`truncated: false\` (the requested sections are whole). It does not repeat the table of contents. On scraped mega-docs with hundreds of headings the digest's \`sections\` list is collapsed to the top levels (\`sectionsCollapsed: true\`, each entry's \`children\` counts the hidden ones); \`--toc\` returns the complete list without the document:
+
+\`\`\`bash
+one --agent actions knowledge <platform> <actionId> --toc
+\`\`\`
 
 ### 4. Execute
 
@@ -11038,6 +11559,8 @@ In \`--agent\` mode, knowledge and search responses include a \`_cache\` field:
 {
   "knowledge": "...",
   "method": "POST",
+  "truncated": true,
+  "sections": [ ... ],
   "_cache": {
     "hit": true,
     "age": 1423,
@@ -11057,6 +11580,9 @@ one --agent actions knowledge <platform> <actionId> --no-cache
 # Check cache status without fetching
 one --agent actions knowledge <platform> <actionId> --cache-status
 
+# Sections and --full are served from the cache once the doc is cached
+one --agent actions knowledge <platform> <actionId> --section "Response Fields"
+
 # Same for search
 one --agent actions search <platform> "<query>" --no-cache
 
@@ -11101,6 +11627,8 @@ The unified memory store is a local, pluggable database (\`embedded-postgres\` b
 The first \`one mem\` call on a fresh install auto-initializes:
 - Backend: \`embedded-postgres\` (Postgres 18 via pgserve; downloads ~52MB of binaries on first use, ~2s on later boots)
 - Cluster path: \`~/.one/pg/cluster/\`, daemon PID/port at \`~/.one/pg/.pgserve.json\`
+- Port: \`5434\` by default. If another program already holds it (a database tunnel, another Postgres), the daemon starts on the next free port and records it in \`.pgserve.json\`. A port pinned with \`mem config set embedded-postgres.port <n>\` is never moved \u2014 a conflict there is an error naming the port.
+- Self-healing: a running daemon is reused only when the Postgres on its port reports this cluster's data directory. A Postgres left holding the cluster by a dead or stuck pgserve is stopped and a fresh daemon started. \`pgserve.log\` is trimmed to its last 1 MB once it passes 10 MB.
 - Embedding provider: \`openai\` if a key is already resolvable AND pgvector is loadable; else \`none\`
 
 If pgvector isn't installed in the bundled Postgres (the default binary distribution doesn't ship it yet), the schema applies cleanly without an \`embedding\` column, all FTS paths work, and \`mem doctor\` emits an \`_upgrade\` block pointing at \`brew install pgvector\` when an OpenAI key is present.
@@ -11751,8 +12279,9 @@ Every \`sync X\` command is also exposed as \`mem sync X\` \u2014 same handlers,
   logs/{platform}.log                 # cron run logs
   locks/{platform}_{model}/           # cross-process sync locks
 ~/.one/pg/cluster/                    # unified memory store \u2014 embedded Postgres data dir
-~/.one/pg/.pgserve.json               # daemon PID/port file (cleared on stop)
-~/.one/pg/pgserve.log                 # daemon stdout/stderr
+~/.one/pg/.pgserve.json               # daemon PID/port file
+~/.one/pg/.pgserve.lock               # held while a CLI process starts the daemon
+~/.one/pg/pgserve.log                 # daemon stdout/stderr (trimmed to 1 MB past 10 MB)
 ~/.one/config.json                    # apiKey + openaiApiKey + memory config block
 ~/.one/sync/
   schedules.json                      # global schedule registry
@@ -11973,7 +12502,7 @@ common mistakes to avoid. Never guess \u2014 read the skill, then act.
 ### Quick reference:
 - \`one --agent list\` \u2014 See connected platforms and connection keys
 - \`one --agent actions search <platform> "<query>"\` \u2014 Find actions
-- \`one --agent actions knowledge <platform> <actionId>\` \u2014 Read docs (REQUIRED before execute)
+- \`one --agent actions knowledge <platform> <actionId>\` \u2014 Read docs (REQUIRED before execute; a digest \u2014 add \`--section <name>\` or \`--full\` for more)
 - \`one --agent actions execute <platform> <actionId> <connectionKey>\` \u2014 Execute action
 - \`one --agent flow create\` \u2014 Build multi-step workflows
 - \`one --agent relay create\` \u2014 Set up webhook relay (receive events, forward to other platforms)
@@ -12276,7 +12805,7 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
   Workflow (use these in order):
     1. one list                           List connected platforms, keys, and your access on each
     2. one actions search <platform> <q>  Search for actions using natural language
-    3. one actions knowledge <plat> <id>  Get full docs for an action (ALWAYS do this before execute)
+    3. one actions knowledge <plat> <id>  Get docs for an action (ALWAYS do this before execute; --section/--full for more)
     4. one actions execute <p> <id> <key> Execute the action
 
   Guide:
@@ -12546,7 +13075,7 @@ var actions = program.command("actions").alias("a").description("Search, explore
 actions.command("search <platform> <query>").description('Search for actions on a platform (e.g. one actions search gmail "send email")').option("-t, --type <type>", "execute (to run it) or knowledge (to learn about it). Default: knowledge").option("--no-cache", "Bypass the cache and re-fetch from the API (the fresh response still refreshes the cache)").action(async (platform, query, options) => {
   await actionsSearchCommand(platform, query, options);
 });
-actions.command("knowledge <platform> <actionId>").alias("k").description("Get full docs for an action \u2014 MUST call before execute to know required params").option("--no-cache", "Bypass the cache and re-fetch from the API (the fresh response still refreshes the cache)").option("--cache-status", "Print cache metadata without fetching").action(async (platform, actionId, options) => {
+actions.command("knowledge <platform> <actionId>").alias("k").description("Get docs for an action \u2014 MUST call before execute to know required params. In --agent mode returns a digest (request-building sections + a table of contents); load the rest with --section or --full").option("--section <name>", 'Return only the named section(s) \u2014 by heading, id, or alias (e.g. "Response Fields", response, optional). Repeatable or comma-separated', collect, []).option("--full", "Return the whole document instead of the digest").option("--toc", "List every section (id, heading, size) without the document").option("--no-cache", "Bypass the cache and re-fetch from the API (the fresh response still refreshes the cache)").option("--cache-status", "Print cache metadata without fetching").action(async (platform, actionId, options) => {
   await actionsKnowledgeCommand(platform, actionId, options);
 });
 actions.command("execute [platform] [actionId] [connectionKey]").alias("x").allowUnknownOption(true).allowExcessArguments(true).description("Execute an action (or multiple with --parallel, separated by --)").option("-d, --data <json>", "Request body as JSON").option("--path-vars <json>", "Path variables as JSON").option("--query-params <json>", "Query parameters as JSON").option("--headers <json>", "Additional headers as JSON").option("--form-data", "Send as multipart/form-data").option("--form-url-encoded", "Send as application/x-www-form-urlencoded").option("--dry-run", "Show request that would be sent without executing").option("--mock", "Return example response without making an API call").option("--skip-validation", "Skip input validation against the action schema").option("--no-cache", "Bypass the cached action details and re-fetch them (the fresh details still refresh the cache; execution itself is never cached)").option("--output <path>", "Save binary response to a file (for non-JSON responses like file downloads)").option("--parallel", "Execute multiple actions concurrently (separate actions with --)").option("--max-concurrency <n>", "Max concurrent actions when using --parallel (default: 5)", "5").action(async (platform, actionId, connectionKey, options) => {