@letta-ai/letta-code 0.28.15 → 0.28.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.28.15",
+  "version": "0.28.17",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -11,6 +11,8 @@
     "LICENSE",
     "README.md",
     "letta.js",
+    "image-resize-worker.js",
+    "assets/tutor-profile.png",
     "scripts",
     "skills",
     "vendor",
@@ -109,6 +111,7 @@
     "lint-staged": "16.2.4",
     "madge": "^8.0.0",
     "minimatch": "^10.0.3",
+    "openai": "^6.48.0",
     "picomatch": "^2.3.1",
     "typescript": "^5.0.0"
   },

package/scripts/source-file-size-baseline.json

@@ -5,16 +5,16 @@
   "src/backend/local/local-backend.ts": 1058,
   "src/backend/local/local-store.ts": 3594,
   "src/backend/pi-stream-adapter.test.ts": 1442,
-  "src/cli/app/AppCoordinator.tsx": 5200,
+  "src/cli/app/AppCoordinator.tsx": 5204,
   "src/cli/app/AppView.tsx": 1750,
   "src/cli/app/use-approval-flow.ts": 1163,
   "src/cli/app/use-configuration-handlers.ts": 1392,
-  "src/cli/app/use-conversation-loop.ts": 2935,
+  "src/cli/app/use-conversation-loop.ts": 2936,
   "src/cli/app/use-submit-handler.ts": 4099,
-  "src/cli/components/AgentSelector.tsx": 1151,
+  "src/cli/components/AgentSelector.tsx": 1111,
   "src/cli/components/InputRich.tsx": 2219,
-  "src/cli/components/ModelSelector.tsx": 1204,
-  "src/cli/components/ProviderSelector.tsx": 1676,
+  "src/cli/components/ModelSelector.tsx": 1213,
+  "src/cli/components/ProviderSelector.tsx": 1682,
   "src/cli/components/ToolCallMessageRich.tsx": 1109,
   "src/cli/helpers/accumulator.ts": 1596,
   "src/cli/helpers/reflection-transcript.ts": 2080,
@@ -26,14 +26,14 @@
   "src/hooks/integration.test.ts": 1147,
   "src/index.ts": 2803,
   "src/mods/learning-harness.ts": 2434,
-  "src/mods/mod-engine.test.ts": 2178,
-  "src/mods/mod-engine.ts": 1879,
+  "src/mods/mod-engine.test.ts": 2132,
+  "src/mods/mod-engine.ts": 1838,
   "src/mods/package-installer.test.ts": 1248,
   "src/mods/package-installer.ts": 1201,
   "src/mods/package-registry.ts": 1033,
   "src/permissions/read-only-shell.test.ts": 1303,
   "src/permissions/read-only-shell.ts": 2009,
-  "src/providers/chatgpt-usage-service.ts": 1115,
+  "src/providers/chatgpt-usage-service.ts": 1112,
   "src/settings-manager.test.ts": 1669,
   "src/settings-manager.ts": 2113,
   "src/tools/impl/enter-worktree.ts": 1260,
@@ -41,12 +41,12 @@
   "src/tools/manager.ts": 3282,
   "src/tools/tool-execution-context.test.ts": 1422,
   "src/types/protocol_v2.ts": 2943,
-  "src/websocket/listen-client-concurrency.test.ts": 3016,
+  "src/websocket/listen-client-concurrency.test.ts": 3017,
   "src/websocket/listen-client-protocol.test.ts": 6723,
   "src/websocket/listener/commands/channels.ts": 1390,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1030,
-  "src/websocket/listener/lifecycle.ts": 1766,
+  "src/websocket/listener/lifecycle.ts": 1762,
   "src/websocket/listener/protocol-inbound.ts": 2279,
-  "src/websocket/listener/protocol-outbound.ts": 1282
+  "src/websocket/listener/protocol-outbound.ts": 1278
 }

package/skills/creating-mods/SKILL.md

@@ -118,7 +118,7 @@ Agents can inspect local mod diagnostics at:
 ## Rules
 
 - Do not create project mods.
-- Custom provider mods are local-backend/local-agent only. They do not add providers for Constellation/cloud agents.
+- Custom provider mods are local-backend/local-agent only. They do not add providers for agents managed through the Letta API.
 - Provider mods may run in a provider-only listener context; keep provider registration independent from commands/tools/UI and guard everything else.
 - Direct mod files should not assume third-party npm packages are available. Use Node/Bun built-ins unless packaging is explicitly requested.
 - Do not do surprising side effects on startup; mods activate on app start and `/reload`.

package/skills/creating-mods/references/architecture.md

@@ -139,7 +139,7 @@ ctx.conversation.updateLlmConfig(opts) // change model / reasoning effort / cont
 
 A forked handle keeps the same agent/backend defaults and targets the forked conversation. Use forked handles for background model work. Use `getHistory({ limit, order, includeErrors })` when local logic needs conversation context.
 
-`updateLlmConfig({ model?, reasoningEffort?, contextWindow?, scope? })` changes the model, reasoning effort, and/or context window, and works across local and Constellation backends. Only the fields you pass change; the rest are preserved, so `updateLlmConfig({ contextWindow })` adjusts just the context window without touching the model or reasoning effort. `scope` defaults to `"conversation"` (a conversation-scoped override that leaves the agent's default untouched); pass `scope: "agent"` to change the agent default. Changing reasoning effort without a model resolves the current model to rebuild provider-specific settings. The change takes effect on the next turn (the model is resolved per provider request).
+`updateLlmConfig({ model?, reasoningEffort?, contextWindow?, scope? })` changes the model, reasoning effort, and/or context window, and works across local and Letta Cloud backends. Only the fields you pass change; the rest are preserved, so `updateLlmConfig({ contextWindow })` adjusts just the context window without touching the model or reasoning effort. `scope` defaults to `"conversation"` (a conversation-scoped override that leaves the agent's default untouched); pass `scope: "agent"` to change the agent default. Changing reasoning effort without a model resolves the current model to rebuild provider-specific settings. The change takes effect on the next turn (the model is resolved per provider request).
 
 Tools currently receive `ctx.conversation.getHistory()` but not fork/send helpers. If a tool needs model-side follow-up, return information for the model to act on instead of starting a hidden run from the tool.
 

package/skills/creating-mods/references/commands.md

@@ -112,7 +112,7 @@ export default function activate(letta) {
 
 For commands with `runWhenBusy: true`, do not return `prompt` while the agent is running. Use the scoped conversation handle directly, update a panel/status if available, and return `{ type: "handled" }` quickly.
 
-Use `ctx.conversation` for conversation operations that should work across local and Constellation backends. The handle is bound to the active conversation and backend for that command invocation, so composed flows like fork-then-send stay on the same backend. Use `letta.client` only for server-specific API calls.
+Use `ctx.conversation` for conversation operations that should work across local and Letta Cloud backends. The handle is bound to the active conversation and backend for that command invocation, so composed flows like fork-then-send stay on the same backend. Use `letta.client` only for server-specific API calls.
 
 Common pattern:
 

package/skills/creating-mods/references/events.md

@@ -61,7 +61,7 @@ Lifecycle, turn, tool, compaction, and llm events are wired today.
 
 Lifecycle handlers are notification-only and should not return values. `turn_start` handlers can transform or cancel outbound user-message turns. `tool_start` handlers can transform the tool arguments before execution. Compaction and llm handlers are notification-only.
 
-`compact_start`/`compact_end` and `llm_start`/`llm_end` only fire on the **local backend**, where compaction and provider requests run client-side. On the constellation backend that work happens server-side and these events do not fire, so guard with `letta.capabilities.events.compact` / `letta.capabilities.events.llm` for portable mods.
+`compact_start`/`compact_end` and `llm_start`/`llm_end` only fire on the **local backend**, where compaction and provider requests run client-side. On the Letta Cloud backend that work happens server-side and these events do not fire, so guard with `letta.capabilities.events.compact` / `letta.capabilities.events.llm` for portable mods.
 
 ## Supported events
 

package/skills/creating-mods/references/providers.md

@@ -2,7 +2,7 @@
 
 Use provider mods when the user wants a **local agent** to use a model provider that is not built into `/connect` and `/model`.
 
-Important: provider mods are local-backend/local-agent only. They register local provider metadata for the TUI, headless local runtime, and desktop listener. They do not add providers for Constellation/cloud agents.
+Important: provider mods are local-backend/local-agent only. They register local provider metadata for the TUI, headless local runtime, and desktop listener. They do not add providers for agents managed through the Letta API.
 
 For multi-capability mods that combine a provider with commands, tools, UI, or state, also read `architecture.md`.
 

package/skills/letta-guide/SKILL.md

@@ -14,19 +14,38 @@ how to answer questions about Letta correctly.
 
 1. **Self-inspection first for questions about THIS agent.** "What model are
    you using?", "what tools do you have?", "what's in your memory?" are
-   questions about the running session, not the docs. Answer them from the
-   live environment: your system prompt and agent info, `/status`-style
-   command surfaces, settings files, and MemFS. Do not fetch docs for these.
-2. **Fetch the docs index.** For product questions, fetch
-   `https://docs.letta.com/llms.txt` — a curated index of every current
-   documentation page with descriptions. Pick the most relevant page URLs.
-3. **Fetch the specific pages.** Append `/index.md` to any docs URL for the
-   canonical LLM-friendly markdown version (e.g.
-   `https://docs.letta.com/configuration/models/index.md`). Read the page,
-   then answer. Cite the doc URL(s) you used so the user can go deeper.
-4. **If the docs are unreachable**, say so explicitly, give your best answer,
-   and clearly mark it as possibly out of date with a link to
-   https://docs.letta.com. Never silently fall back to memory.
+   questions about the running session, not the docs. Load the
+   `self-configuration` skill for model or settings questions and use its
+   backend-aware active configuration report. Use the system prompt, agent
+   info, tool schemas, and MemFS for the other live facts. Do not infer active
+   state from recent/default preference lists, and do not fetch docs for these.
+2. **Fetch the docs index directly.** For product questions, run:
+
+   ```bash
+   node <SKILL_DIR>/scripts/fetch-letta-docs.mjs
+   ```
+
+   The helper retrieves `https://docs.letta.com/llms.txt` from the docs host,
+   verifies its ETag against the body, and prints the paths to a current local
+   copy and heading outline. Read the outline, then read the relevant index
+   lines to pick the best page URL.
+3. **Fetch the specific page directly.** Pass the exact canonical URL from the
+   index back to the same helper, for example:
+
+   ```bash
+   node <SKILL_DIR>/scripts/fetch-letta-docs.mjs \
+     --docs-url "https://docs.letta.com/configuration/models/index.md"
+   ```
+
+   Read the returned docs path before running the helper for another URL. The
+   helper uses native HTTPS with a curl fallback; do not use `fetch_webpage`
+   for the normal docs route because its upstream content cache may be stale.
+   Cite the public doc URL so the user can go deeper.
+4. **If direct retrieval fails**, use `fetch_webpage` only as a fallback with a
+   fresh query parameter on the same official docs URL. Disclose that the
+   fallback may be stale. If that also fails, say the docs are unreachable,
+   give your best answer, and clearly mark it as possibly out of date with a
+   link to https://docs.letta.com. Never silently fall back to memory.
 
 ## Hard rules
 
@@ -66,9 +85,9 @@ rather than leaving the user stuck.
 
 ## Caching
 
-Cache fetched pages under the Letta home directory: `~/.letta/docs-cache/`
-(Windows: `%USERPROFILE%\.letta\docs-cache\`). Resolve `~` to an absolute
-path before passing paths to file tools — they do not expand it. Reuse cached
-pages within a session; refetch `llms.txt` when the cached copy is older than
-about a day.
+The helper owns the cache. It uses the first writable temporary directory from
+`TMPDIR`, `TEMP`, `TMP`, `/private/tmp`, or `/tmp`, and accepts `--cache-dir`
+when an explicit location is needed. Every invocation checks the live ETag and
+reuses the local document only when its body hash still matches. Do not create
+or manage a second cache yourself.
 

package/skills/letta-guide/scripts/fetch-letta-docs.mjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import {
+  access,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+
+const DEFAULT_DOCS_URL = "https://docs.letta.com/llms.txt";
+const CACHE_DIRECTORY_NAME = "letta-docs-cache";
+const DOCUMENT_NAME = "letta-docs.md";
+const OUTLINE_NAME = "letta-docs.outline.md";
+const USER_AGENT = "letta-guide";
+const runFile = promisify(execFile);
+
+class DocsFetchError extends Error {
+  constructor(message, cause) {
+    super(message, cause ? { cause } : undefined);
+    this.name = "DocsFetchError";
+  }
+}
+
+function bodyDigest(body) {
+  return createHash("md5").update(body).digest("hex");
+}
+
+function hasProxyEnvironment() {
+  return ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"].some(
+    (key) => Boolean(process.env[key]),
+  );
+}
+
+function temporaryFile(directory, extension) {
+  return path.join(
+    directory,
+    `.letta-docs-${process.pid}-${Date.now()}-${randomBytes(5).toString("hex")}${extension}`,
+  );
+}
+
+function parseHeaderDump(raw) {
+  const responseBlocks = raw
+    .replace(/\r\n/g, "\n")
+    .trim()
+    .split(/\n\n+/)
+    .filter((block) => block.startsWith("HTTP/"));
+  const finalBlock = responseBlocks.at(-1);
+  if (!finalBlock) {
+    throw new DocsFetchError("curl returned no HTTP response headers.");
+  }
+
+  const [statusLine, ...lines] = finalBlock.split("\n");
+  const status = Number(/^HTTP\/\S+\s+(\d{3})/.exec(statusLine)?.[1]);
+  if (!Number.isInteger(status)) {
+    throw new DocsFetchError(
+      `curl returned an invalid status line: ${statusLine}`,
+    );
+  }
+
+  const headers = new Map();
+  for (const line of lines) {
+    const separator = line.indexOf(":");
+    if (separator < 1) continue;
+    headers.set(
+      line.slice(0, separator).trim().toLowerCase(),
+      line.slice(separator + 1).trim(),
+    );
+  }
+  return { headers, status };
+}
+
+async function curlRequest(url, method, cacheDirectory, timeoutMs) {
+  const headersFile = temporaryFile(cacheDirectory, ".headers");
+  const bodyFile = temporaryFile(cacheDirectory, ".body");
+  const executables =
+    process.platform === "win32" ? ["curl.exe", "curl"] : ["curl"];
+  const argumentsList = [
+    "--silent",
+    "--show-error",
+    "--location",
+    "--dump-header",
+    headersFile,
+    "--output",
+    bodyFile,
+    "--user-agent",
+    USER_AGENT,
+    "--max-time",
+    String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+    ...(method === "HEAD" ? ["--head"] : ["--request", method]),
+    url,
+  ];
+
+  let failure;
+  for (const executable of executables) {
+    try {
+      await runFile(executable, argumentsList, { windowsHide: true });
+      const [rawHeaders, body] = await Promise.all([
+        readFile(headersFile, "utf8"),
+        readFile(bodyFile, "utf8"),
+      ]);
+      return { ...parseHeaderDump(rawHeaders), body };
+    } catch (error) {
+      failure = error;
+      if (error?.code !== "ENOENT") break;
+    } finally {
+      await Promise.all([
+        rm(headersFile, { force: true }),
+        rm(bodyFile, { force: true }),
+      ]);
+    }
+  }
+  throw new DocsFetchError(
+    failure?.code === "ENOENT"
+      ? "curl is unavailable in this environment."
+      : `curl could not ${method} ${url}.`,
+    failure,
+  );
+}
+
+async function nodeRequest(url, method, _cacheDirectory, timeoutMs) {
+  if (typeof fetch !== "function") {
+    throw new DocsFetchError("Native fetch requires Node.js 18 or newer.");
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      method,
+      headers: { "User-Agent": USER_AGENT },
+      redirect: "follow",
+      signal: controller.signal,
+    });
+    const headers = new Map();
+    response.headers.forEach((value, key) => {
+      headers.set(key.toLowerCase(), value);
+    });
+    return {
+      body: method === "HEAD" ? "" : await response.text(),
+      headers,
+      status: response.status,
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function requestDocument(url, method, cacheDirectory, timeoutMs) {
+  const transports = hasProxyEnvironment()
+    ? [curlRequest, nodeRequest]
+    : [nodeRequest, curlRequest];
+  let failure;
+  for (const transport of transports) {
+    try {
+      const result = await transport(url, method, cacheDirectory, timeoutMs);
+      if (result.status < 200 || result.status >= 300) {
+        throw new DocsFetchError(
+          `${method} ${url} failed with HTTP ${result.status}.`,
+        );
+      }
+      return result;
+    } catch (error) {
+      failure = error;
+    }
+  }
+  throw new DocsFetchError(`${method} ${url} could not be fetched.`, failure);
+}
+
+function digestFromEtag(headers) {
+  const etag = headers.get("etag") ?? "";
+  const digest = /^(?:W\/)?"([a-f0-9]{32})"$/i.exec(etag)?.[1];
+  if (!digest) {
+    throw new DocsFetchError(
+      "Letta docs response is missing a content-MD5 ETag.",
+    );
+  }
+  return digest.toLowerCase();
+}
+
+async function nearestExistingDirectory(candidate) {
+  let current = path.resolve(candidate);
+  while (true) {
+    try {
+      return (await stat(current)).isDirectory() ? current : null;
+    } catch (error) {
+      if (error?.code !== "ENOENT") return null;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+async function writableCacheDirectory(candidate) {
+  if (!candidate) return null;
+  const resolved = path.resolve(candidate);
+  try {
+    const existing = await stat(resolved);
+    if (!existing.isDirectory()) return null;
+  } catch (error) {
+    if (error?.code !== "ENOENT") return null;
+  }
+  const existingParent = await nearestExistingDirectory(resolved);
+  if (!existingParent) return null;
+  try {
+    await access(existingParent, fsConstants.W_OK | fsConstants.X_OK);
+    return resolved;
+  } catch {
+    return null;
+  }
+}
+
+async function selectCacheDirectory(override) {
+  if (override) return writableCacheDirectory(override);
+  const candidates = [process.env.TMPDIR, process.env.TEMP, process.env.TMP]
+    .filter(Boolean)
+    .map((directory) => path.join(directory, CACHE_DIRECTORY_NAME));
+  if (process.platform !== "win32") {
+    candidates.push(
+      path.join("/private/tmp", CACHE_DIRECTORY_NAME),
+      path.join("/tmp", CACHE_DIRECTORY_NAME),
+    );
+  }
+  for (const candidate of new Set(candidates)) {
+    const usable = await writableCacheDirectory(candidate);
+    if (usable) return usable;
+  }
+  return null;
+}
+
+async function atomicWrite(destination, contents) {
+  const temporary = temporaryFile(
+    path.dirname(destination),
+    `.${path.basename(destination)}.tmp`,
+  );
+  await writeFile(temporary, contents, "utf8");
+  await rename(temporary, destination);
+}
+
+function createOutline(markdown) {
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  const entries = [];
+  let fenced = false;
+  lines.forEach((line, index) => {
+    if (/^\s*(?:```|~~~)/.test(line)) {
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const heading = /^(#{2,3})\s+(.+?)\s*$/.exec(line);
+    if (!heading) return;
+    entries.push({
+      level: heading[1].length,
+      title: heading[2]
+        .replace(/\s+#+\s*$/, "")
+        .replace(/\s+/g, " ")
+        .trim(),
+      start: index + 1,
+      end: lines.length,
+    });
+  });
+  entries.forEach((entry, index) => {
+    const nextPeer = entries
+      .slice(index + 1)
+      .find((candidate) => candidate.level <= entry.level);
+    if (nextPeer) entry.end = nextPeer.start - 1;
+  });
+
+  const lowestLevel = entries.length
+    ? Math.min(...entries.map((entry) => entry.level))
+    : 2;
+  const text = entries.length
+    ? entries
+        .map(
+          (entry) =>
+            `${"  ".repeat(entry.level - lowestLevel)}- ${entry.title} (lines ${entry.start}-${entry.end})`,
+        )
+        .join("\n")
+    : "No markdown headings found.";
+  return {
+    headingCount: entries.length,
+    lineCount: lines.length,
+    markdown: `# Letta Docs Outline\n\n${text}\n`,
+  };
+}
+
+async function cachedBody(documentPath, expectedDigest) {
+  try {
+    const body = await readFile(documentPath, "utf8");
+    return bodyDigest(body) === expectedDigest ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchLettaDocs({
+  docsUrl = DEFAULT_DOCS_URL,
+  cacheDir,
+  timeoutMs = 30000,
+} = {}) {
+  const selectedCache = await selectCacheDirectory(cacheDir);
+  if (!selectedCache) {
+    throw new DocsFetchError(
+      "No writable docs cache is available; pass --cache-dir to override.",
+    );
+  }
+  await mkdir(selectedCache, { recursive: true });
+
+  const documentPath = path.join(selectedCache, DOCUMENT_NAME);
+  const outlinePath = path.join(selectedCache, OUTLINE_NAME);
+  const head = await requestDocument(docsUrl, "HEAD", selectedCache, timeoutMs);
+  const expectedDigest = digestFromEtag(head.headers);
+  let body = await cachedBody(documentPath, expectedDigest);
+  const cacheStatus = body === null ? "updated" : "hit";
+
+  if (body === null) {
+    const get = await requestDocument(docsUrl, "GET", selectedCache, timeoutMs);
+    const getDigest = digestFromEtag(get.headers);
+    if (getDigest !== expectedDigest) {
+      throw new DocsFetchError(
+        `ETag changed between HEAD and GET for ${docsUrl}.`,
+      );
+    }
+    if (bodyDigest(get.body) !== expectedDigest) {
+      throw new DocsFetchError(
+        `ETag did not match the fetched body for ${docsUrl}.`,
+      );
+    }
+    body = get.body;
+    await atomicWrite(documentPath, body);
+  }
+
+  const outline = createOutline(body);
+  await atomicWrite(outlinePath, outline.markdown);
+  return {
+    outline: outline.markdown,
+    status: {
+      docsUrl,
+      etagMd5: expectedDigest,
+      fetchedMd5: bodyDigest(body),
+      contentMatchesEtag: true,
+      cacheStatus,
+      cacheDir: selectedCache,
+      docsPath: documentPath,
+      outlinePath,
+      checkedAt: new Date().toISOString(),
+      lineCount: outline.lineCount,
+      headingCount: outline.headingCount,
+    },
+  };
+}
+
+function parseArguments(argv) {
+  const result = {
+    docsUrl: DEFAULT_DOCS_URL,
+    cacheDir: undefined,
+    timeoutMs: 30000,
+    statusJson: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--docs-url") result.docsUrl = argv[++index];
+    else if (value === "--cache-dir") result.cacheDir = argv[++index];
+    else if (value === "--timeout-ms") result.timeoutMs = Number(argv[++index]);
+    else if (value === "--status-json") result.statusJson = true;
+    else throw new DocsFetchError(`Unknown argument: ${value}`);
+  }
+  if (!result.docsUrl) throw new DocsFetchError("--docs-url cannot be empty.");
+  if (!Number.isFinite(result.timeoutMs) || result.timeoutMs <= 0) {
+    throw new DocsFetchError("--timeout-ms must be a positive number.");
+  }
+  return result;
+}
+
+function outputFor(status, outline) {
+  return [
+    `Docs path: ${status.docsPath}`,
+    `Outline path: ${status.outlinePath}`,
+    status.cacheStatus === "hit"
+      ? "Docs status: local document was already current."
+      : "Docs status: local document was updated.",
+    "",
+    outline,
+  ].join("\n");
+}
+
+function errorChain(error) {
+  const messages = [];
+  let current = error;
+  while (current) {
+    messages.push(
+      current instanceof Error
+        ? `${current.name}: ${current.message}`
+        : String(current),
+    );
+    current = current?.cause;
+  }
+  return messages.join("\nCaused by: ");
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const result = await fetchLettaDocs(options);
+  process.stdout.write(outputFor(result.status, result.outline));
+  if (options.statusJson) console.error(JSON.stringify(result.status));
+}
+
+if (
+  process.argv[1] &&
+  pathToFileURL(process.argv[1]).href === import.meta.url
+) {
+  main().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    if (hasProxyEnvironment()) {
+      console.error(
+        "Hint: proxy variables are set, so curl is tried before native fetch.",
+      );
+    } else if (typeof fetch !== "function") {
+      console.error("Hint: install curl or use Node.js 18 or newer.");
+    } else if (process.platform === "win32") {
+      console.error("Hint: use a cache directory under %TEMP% or %TMP%.");
+    }
+    console.error("");
+    console.error("Details:");
+    console.error(errorChain(error));
+    process.exitCode = 1;
+  });
+}
+
+export { DEFAULT_DOCS_URL, createOutline, fetchLettaDocs };