@withone/cli 1.56.0 → 1.57.0

package/README.md

@@ -24,7 +24,7 @@
   <a href="https://withone.ai/knowledge"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.withone.ai%2Fopen%2Fcount%2Ftools" alt="tools"></a>
 </p>
 
-One gives your AI agent authenticated access to 600+ platforms - Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else - through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.
+One gives your AI agent authenticated access to 750+ platforms - Gmail, Slack, Shopify, HubSpot, Stripe, Notion, and everything else - through a single interface. No API keys to juggle, no OAuth flows to build, no request formats to memorize. Connect a platform once, and your agent can search for actions, read the docs, and execute API calls in seconds.
 
 ## Install
 
@@ -250,7 +250,7 @@ Shows the connection details and asks for confirmation before deleting. Use `--f
 
 ### `one platforms`
 
-Browse all 600+ available platforms.
+Browse all 750+ available platforms.
 
 ```bash
 one platforms              # all platforms
@@ -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

@@ -1578,6 +1578,25 @@ function startCallbackServer(expectedState) {
     tryListen();
   });
 }
+function wrapForNote(text5, width = noteWidth()) {
+  const lines = [];
+  for (const line of text5.split("\n")) {
+    let rest = line;
+    while (rest.length > width) {
+      const space = rest.lastIndexOf(" ", width);
+      const cut = space > 0 ? space : width;
+      lines.push(rest.slice(0, cut));
+      rest = rest.slice(cut).trimStart();
+    }
+    lines.push(rest);
+  }
+  return lines.join("\n");
+}
+function noteWidth() {
+  const columns = process.stdout.columns;
+  const usable = (typeof columns === "number" && columns > 0 ? columns : 80) - 8;
+  return Math.max(usable, 40);
+}
 async function browserLogin(opts) {
   const state = crypto.randomUUID();
   const spin = createSpinner();
@@ -1598,13 +1617,17 @@ ${authUrl}
 `);
   } else {
     note(
-      `If the browser doesn't open, visit:
-${authUrl}
+      wrapForNote(
+        `The consent page records this on the key, so you can find the install later.
 
-The consent page records this on the key so you can find the install later:
-${describeInstallContext(context)}`,
-      "Opening browser for authentication..."
+${describeInstallContext(context)}`
+      ),
+      "This install"
     );
+    console.log();
+    console.log("  Opening your browser. If it doesn't open, visit:");
+    console.log(authUrl);
+    console.log();
   }
   try {
     await open2(authUrl);
@@ -1719,7 +1742,7 @@ async function loginCommand() {
   console.log(pc16.cyan("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log(pc16.cyan("  \u2502"));
   console.log(pc16.cyan("  \u2502  The One CLI (`one`) is now installed on this machine. It"));
-  console.log(pc16.cyan("  \u2502  lets you interact with 600+ third-party platforms (Gmail,"));
+  console.log(pc16.cyan("  \u2502  lets you interact with 750+ third-party platforms (Gmail,"));
   console.log(pc16.cyan("  \u2502  Slack, Shopify, HubSpot, Stripe, GitHub, etc.) through"));
   console.log(pc16.cyan("  \u2502  their APIs. Whenever you need to interact with any"));
   console.log(pc16.cyan("  \u2502  third-party platform or external service, use the `one`"));
@@ -2311,7 +2334,7 @@ function printOnboardingPrompt() {
   console.log(pc4.cyan("  \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log(pc4.cyan("  \u2502"));
   console.log(pc4.cyan("  \u2502  The One CLI (`one`) is now installed on this machine. It"));
-  console.log(pc4.cyan("  \u2502  lets you interact with 600+ third-party platforms (Gmail,"));
+  console.log(pc4.cyan("  \u2502  lets you interact with 750+ third-party platforms (Gmail,"));
   console.log(pc4.cyan("  \u2502  Slack, Shopify, HubSpot, Stripe, GitHub, etc.) through"));
   console.log(pc4.cyan("  \u2502  their APIs. Whenever you need to interact with any"));
   console.log(pc4.cyan("  \u2502  third-party platform or external service, use the `one`"));
@@ -2432,18 +2455,23 @@ ${resolutionHint}`,
   printOnboardingPrompt();
   p3.outro("Done! Paste the prompt above to your AI agent.");
 }
+function lime(text5) {
+  if (!pc4.isColorSupported) return text5;
+  const truecolor = process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit";
+  return truecolor ? `\x1B[38;2;204;255;0m${text5}\x1B[39m` : pc4.green(text5);
+}
 function printBanner() {
   console.log();
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
-  console.log(pc4.yellow("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588      \u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588    \u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588       "));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588     \u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
+  console.log(lime("  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588      \u2588\u2588\u2588\u2588\u2588   \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588"));
   console.log();
   console.log(pc4.dim("  I N F R A S T R U C T U R E   F O R   A G E N T S"));
   console.log();
@@ -2475,7 +2503,7 @@ async function promptConnectIntegrations(apiKey, connParams) {
         label: i.label,
         hint: i.hint
       })),
-      { value: "more", label: "Browse all 600+ platforms" },
+      { value: "more", label: "Browse all 750+ platforms" },
       { value: "skip", label: "Skip for now", hint: "you can always run one add later" }
     ];
     const message = first ? "Connect your first integration?" : "Connect another?";
@@ -3081,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) {
@@ -3278,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
@@ -3288,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;
     }
@@ -10660,7 +11173,7 @@ Before using any feature, read its guide section first: \`one guide actions\`, \
 
 ## Features
 
-### 1. Actions \u2014 Execute API calls on 600+ platforms
+### 1. Actions \u2014 Execute API calls on 750+ platforms
 Search for actions, read their docs, and execute them. This is the core workflow.
 
 **Quick start:**
@@ -10805,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
 
@@ -11010,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,
@@ -11029,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
 
@@ -11885,7 +12439,7 @@ function buildStep1() {
     nextCommand: "one onboard --step 2",
     message: `# One CLI \u2014 Agent Onboarding
 
-You now have access to the One CLI. It connects you to 600+ platforms
+You now have access to the One CLI. It connects you to 750+ platforms
 (Gmail, Slack, Stripe, Notion, etc.) \u2014 you'll learn the details shortly.
 
 IMPORTANT: Your only task right now is to send the message below to the
@@ -11895,7 +12449,7 @@ Do not offer demos yet. Just send this message and wait for their reply:
 ---
 
 I just got access to the One CLI \u2014 it connects me to your platforms like
-Gmail, Slack, Stripe, and 600+ others so I can work with them directly.
+Gmail, Slack, Stripe, and 750+ others so I can work with them directly.
 I'll show you what I can do in a moment.
 
 First, one quick setup step: right now only this conversation knows about
@@ -11924,7 +12478,7 @@ If they declined, skip this section.
 ## One CLI \u2014 Platform Integrations
 
 The One CLI (\`one\`) is installed and configured on this machine. It is a
-command-line tool that gives AI agents the ability to interact with 600+
+command-line tool that gives AI agents the ability to interact with 750+
 third-party platforms (Gmail, Slack, Shopify, HubSpot, Stripe, GitHub,
 Notion, Salesforce, etc.) through a single, unified interface.
 
@@ -11945,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)
@@ -12019,7 +12573,7 @@ function buildStep3(connections) {
 The user can connect any of these popular platforms:
 Gmail, Google Calendar, Slack, Notion, Shopify, Stripe, HubSpot, GitHub,
 Salesforce, QuickBooks, Asana, Jira, Linear, Intercom, Zendesk, Twilio,
-and 600+ more. Run \`one platforms\` for the full list.`);
+and 750+ more. Run \`one platforms\` for the full list.`);
   sections.push("## Onboarding complete!\n\nYou're all set. Use `one --agent guide` any time you need the full reference.");
   return {
     step: 3,
@@ -12050,7 +12604,7 @@ platform before you can start using actions. Suggest they run:
   one add slack
   one add <any-platform>
 
-Run \`one platforms\` to see all 600+ available platforms.`;
+Run \`one platforms\` to see all 750+ available platforms.`;
   }
   const header = `## Current State
 
@@ -12234,7 +12788,7 @@ silenceWarningsInAgentMode();
 var require4 = createRequire3(import.meta.url);
 var { version } = require4("../package.json");
 var program = new Command();
-program.name("one").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`One CLI \u2014 Connect AI agents to 600+ platforms through one interface.
+program.name("one").option("--agent", "Machine-readable JSON output (no colors, spinners, or prompts)").description(`One CLI \u2014 Connect AI agents to 750+ platforms through one interface.
 
   Setup:
     one login                             Authenticate via browser; the consent page records where this CLI is installed
@@ -12248,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:
@@ -12306,7 +12860,7 @@ program.name("one").option("--agent", "Machine-readable JSON output (no colors,
         -d '{"to":"j@example.com","subject":"Hello","body":"Hi!","connectionKey":"live::gmail::default::abc123"}'
 
   Platform names are lowercase; multi-word names use dashes (e.g. hubspot, ship-station, google-calendar).
-  Run 'one platforms' to browse all 600+ available platforms.`).version(version);
+  Run 'one platforms' to browse all 750+ available platforms.`).version(version);
 var updateCheckPromise;
 program.hook("preAction", (thisCommand, actionCommand) => {
   const opts = program.opts();
@@ -12518,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.0",
+  "version": "1.57.0",
   "description": "CLI for managing One",
   "type": "module",
   "files": [

package/skills/one/SKILL.md

@@ -20,7 +20,7 @@ description: |
 
 # One CLI
 
-You have access to the One CLI which lets you interact with 600+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
+You have access to the One CLI which lets you interact with 750+ third-party platforms through their APIs. Always include the `--agent` flag right after `one` for structured JSON output.
 
 If the user wants a separate API key / connections for a specific project (vs. their default), walk them through running `one init` from that project folder and picking the "project" scope — see `references/scoping.md`. For monorepo subprojects (where a parent already has `.git`/`package.json`), have them `mkdir .one` in the subproject first so the config is keyed to that dir, not the monorepo root.
 
@@ -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