@withone/cli 1.56.1 → 1.57.0

package/README.md

@@ -280,6 +280,18 @@ one actions knowledge shopify 67890abcdef
 
 Always read the knowledge before executing. It tells you exactly what parameters are required, what format they need, and any platform-specific quirks.
 
+In `--agent` mode the response is a **digest**: request-building sections in full (method/URL, headers, description, enforcement rules, required and optional parameters, sample request, gotchas, error handling) plus a table of contents for the rest. Response shapes, response-field tables, and worked examples — the bulk of every large doc — are loaded on demand:
+
+```bash
+one --agent actions knowledge github <actionId>                              # digest + sections[] table of contents
+one --agent actions knowledge github <actionId> --section "Response Fields"  # one section, by heading or id
+one --agent actions knowledge github <actionId> --section response,examples  # several, by alias
+one --agent actions knowledge github <actionId> --full                       # whole document
+one --agent actions knowledge github <actionId> --toc                        # every section id, no document
+```
+
+The JSON carries `truncated`, `sections[]` (the omitted sections: id, heading, chars), and `more` (the commands to load the rest); the markdown ends with the same notice so it is never mistaken for the complete doc. Small documents are returned whole. Section requests are served from the local cache. Human (non-agent) output always prints the full document; `--section` works there too.
+
 ### `one actions execute <platform> <actionId> <connectionKey>`
 
 Execute an API action on a connected platform.
@@ -354,6 +366,7 @@ Knowledge and search commands also support cache flags:
 ```bash
 one actions knowledge gmail <actionId> --no-cache       # Skip cache, fetch fresh
 one actions knowledge gmail <actionId> --cache-status   # Check cache status
+one actions knowledge gmail <actionId> --section response   # Served from the cached doc, no fetch
 one actions search gmail "send email" --no-cache        # Skip cache for search
 one actions execute gmail <actionId> <key> --no-cache   # Fresh action-details lookup
 ```

package/dist/index.js

@@ -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;
     }
@@ -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
 
@@ -11973,7 +12499,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 +12802,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 +13072,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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/cli",
-  "version": "1.56.1",
+  "version": "1.57.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/SKILL.md

@@ -89,6 +89,26 @@ one --agent actions knowledge <platform> <actionId>
 
 This tells you exactly what parameters are required, how to structure the request, and which flags to use. Never skip this step — without it you'll guess wrong on parameters.
 
+**You get a digest, not always the whole document.** Large docs are trimmed to the request-building sections (method/URL, headers, description, rules, required + optional parameters, sample request, gotchas, error handling). The response tells you what was left out:
+
+- `truncated: true` — some sections are omitted. `truncated: false` — you have everything (and no `sections` list is sent).
+- `sections[]` — the omitted sections only, each with `id`, `heading`, `chars`, and `included` (`false` / `"partial"`). Included sections are the headings you can see in the markdown.
+- The markdown itself ends with a notice naming the omitted sections and the exact commands to load them.
+
+Load more only when you need it (response shapes, response fields, worked examples). Served from the local cache, no network:
+
+```bash
+one --agent actions knowledge <platform> <actionId> --section "Response Fields"   # by heading
+one --agent actions knowledge <platform> <actionId> --section response,optional    # by alias, several at once
+one --agent actions knowledge <platform> <actionId> --full                         # whole document
+```
+
+Aliases: `response`, `fields`, `optional`, `required`, `examples`, `errors`, `success`, `body`, `query`, `path`, `notes`, `behavior`, `gotchas`. An unknown name returns an error listing every available section — retry with one of those ids.
+
+- A `--section` response has `truncated: false` (you got the whole section) and `resolved` (which ids your names matched). It does not repeat the table of contents.
+- If the digest says `sectionsCollapsed: true`, the doc has hundreds of headings and `sections` shows only the top omitted levels (`children` = hidden count). `--toc` lists every heading without the document.
+- Sections named `(appendix)` in the notice are appended reference chunks or companion endpoints, not the action doc itself.
+
 ### 4. Execute
 
 ```bash
@@ -164,6 +184,7 @@ Knowledge and search responses are cached locally (`~/.one/cache/`). Subsequent
 - In `--agent` mode, responses include a `_cache` field: `{"hit": true, "age": 1423, "fresh": true}`; execute responses include `"_preflight": {"cache": "hit"|"miss"}`
 - Use `--no-cache` to force a fresh fetch: works on `knowledge`, `search`, and `execute` (refreshes execute's action-details lookup)
 - Use `--cache-status` to check cache state without fetching
+- `knowledge --section <name>` and `--full` read from the cached document — no extra API call once the doc is cached
 - Manage cache: `one cache list`, `one cache clear`, `one cache update-all`
 - Execution responses are NEVER cached — the action always runs live; only action metadata (docs, method, path, schema) is cached