@docmana/sdk 0.3.5 → 0.8.0

package/dist/cli.mjs

@@ -1,14 +1,42 @@
 #!/usr/bin/env node
 
-// src/cli.ts
-import { existsSync, realpathSync } from "fs";
-import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
-import { dirname, resolve } from "path";
-import { createInterface } from "readline/promises";
+// src/cli/cli.ts
+import { realpathSync } from "fs";
+import { resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
 import { Command, CommanderError } from "commander";
 
-// src/errors.ts
+// src/sdk/config.ts
+var DEFAULTS = {
+  tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
+  scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
+  timeoutMs: 3e5,
+  pollIntervalMs: 2e3,
+  pollMaxIntervalMs: 1e4
+};
+function resolveConfig(config) {
+  if (!config.apiBaseUrl) throw new Error("DocmanaConfig.apiBaseUrl is required");
+  if (!config.accessToken && !config.getAccessToken) {
+    throw new Error("DocmanaConfig.accessToken or DocmanaConfig.getAccessToken is required");
+  }
+  const apiBaseUrl = normalizeApiBaseUrl(config.apiBaseUrl);
+  return {
+    apiBaseUrl,
+    accessToken: config.accessToken,
+    getAccessToken: config.getAccessToken,
+    timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
+    pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
+    pollMaxIntervalMs: config.pollMaxIntervalMs ?? DEFAULTS.pollMaxIntervalMs,
+    fetchImpl: config.fetch ?? fetch,
+    headers: config.headers ?? {}
+  };
+}
+function normalizeApiBaseUrl(value) {
+  const trimmed = value.replace(/\/+$/, "");
+  return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
+}
+
+// src/sdk/errors.ts
 var DocmanaError = class extends Error {
   status;
   requestId;
@@ -61,7 +89,14 @@ var DocmanaAbortError = class extends DocmanaError {
     super(message, { code: "aborted" });
   }
 };
-function errorFromResponse(status, message, requestId) {
+var DocmanaRateLimitError = class extends DocmanaError {
+  retryAfterMs;
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: "rate_limited" });
+    this.retryAfterMs = opts.retryAfterMs;
+  }
+};
+function errorFromResponse(status, message, requestId, retryAfterMs) {
   const opts = { status, requestId };
   switch (status) {
     case 400:
@@ -72,118 +107,14 @@ function errorFromResponse(status, message, requestId) {
       return new DocmanaPermissionError(message, opts);
     case 404:
       return new DocmanaNotFoundError(message, opts);
+    case 429:
+      return new DocmanaRateLimitError(message, { ...opts, retryAfterMs });
     default:
       return new DocmanaError(message, opts);
   }
 }
 
-// src/auth/token-manager.ts
-var SAFETY_MARGIN_MS = 6e4;
-var TokenManager = class {
-  constructor(opts) {
-    this.opts = opts;
-  }
-  opts;
-  token = null;
-  expiresAt = 0;
-  inflight = null;
-  invalidate() {
-    this.token = null;
-    this.expiresAt = 0;
-    void this.opts.tokenCache?.clear().catch(() => void 0);
-  }
-  async getToken() {
-    if (this.token && Date.now() < this.expiresAt) return this.token;
-    const cached = await this.readCachedToken();
-    if (cached) return cached;
-    if (this.inflight) return this.inflight;
-    this.inflight = this.acquire().finally(() => {
-      this.inflight = null;
-    });
-    return this.inflight;
-  }
-  async acquire() {
-    const body = new URLSearchParams({
-      grant_type: "client_credentials",
-      client_id: this.opts.clientId,
-      client_secret: this.opts.clientSecret,
-      scope: this.opts.scope
-    });
-    const res = await this.opts.fetchImpl(this.opts.tokenEndpoint, {
-      method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      body: body.toString()
-    });
-    if (!res.ok) {
-      throw new DocmanaAuthError("Failed to acquire Docmana access token", { status: res.status });
-    }
-    const json = await res.json();
-    if (typeof json.access_token !== "string" || json.access_token.length === 0 || typeof json.expires_in !== "number" || !Number.isFinite(json.expires_in)) {
-      throw new DocmanaAuthError("Malformed token response from Docmana CIAM", {
-        status: res.status
-      });
-    }
-    this.token = json.access_token;
-    this.expiresAt = Date.now() + json.expires_in * 1e3 - SAFETY_MARGIN_MS;
-    await this.writeCachedToken().catch(() => void 0);
-    return this.token;
-  }
-  async readCachedToken() {
-    if (!this.opts.tokenCache) return null;
-    let entry;
-    try {
-      entry = await this.opts.tokenCache.read();
-    } catch {
-      return null;
-    }
-    if (!entry) return null;
-    if (entry.clientId !== this.opts.clientId || entry.tokenEndpoint !== this.opts.tokenEndpoint || entry.scope !== this.opts.scope || Date.now() >= entry.expiresAt) {
-      await this.opts.tokenCache.clear().catch(() => void 0);
-      return null;
-    }
-    this.token = entry.accessToken;
-    this.expiresAt = entry.expiresAt;
-    return this.token;
-  }
-  async writeCachedToken() {
-    if (!this.opts.tokenCache || !this.token) return;
-    await this.opts.tokenCache.write({
-      accessToken: this.token,
-      expiresAt: this.expiresAt,
-      clientId: this.opts.clientId,
-      tokenEndpoint: this.opts.tokenEndpoint,
-      scope: this.opts.scope
-    });
-  }
-};
-
-// src/config.ts
-var DEFAULTS = {
-  apiBaseUrl: "https://api.docmana.ai",
-  tokenEndpoint: "https://4fe70f5b-e013-4f65-9fa7-3109a33beba5.ciamlogin.com/4fe70f5b-e013-4f65-9fa7-3109a33beba5/oauth2/v2.0/token",
-  scope: "api://d781e6ba-cc08-4618-8099-ad968abd2b9e/.default",
-  timeoutMs: 3e5,
-  pollIntervalMs: 2e3
-};
-function resolveConfig(config) {
-  if (!config.clientId) throw new Error("DocmanaConfig.clientId is required");
-  if (!config.clientSecret) throw new Error("DocmanaConfig.clientSecret is required");
-  const apiBaseUrl = (config.apiBaseUrl ?? DEFAULTS.apiBaseUrl).replace(/\/+$/, "");
-  return {
-    clientId: config.clientId,
-    clientSecret: config.clientSecret,
-    apiBaseUrl,
-    tokenEndpoint: config.tokenEndpoint ?? DEFAULTS.tokenEndpoint,
-    scope: config.scope ?? DEFAULTS.scope,
-    timeoutMs: config.timeoutMs ?? DEFAULTS.timeoutMs,
-    pollIntervalMs: config.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
-    fetchImpl: config.fetch ?? fetch,
-    headers: config.headers ?? {},
-    tokenCache: config.tokenCache
-  };
-}
-
-// src/http/http-client.ts
+// src/sdk/http/http-client.ts
 var HttpClient = class {
   constructor(opts) {
     this.opts = opts;
@@ -199,21 +130,29 @@ var HttpClient = class {
       throw new DocmanaError("Invalid JSON response from Docmana", { status: res.status });
     }
   }
+  async requestBytes(method, path, options = {}) {
+    const res = await this.requestRaw(method, path, options);
+    return { bytes: new Uint8Array(await res.arrayBuffer()), headers: res.headers };
+  }
   async requestRaw(method, path, options = {}) {
     let res = await this.send(method, path, options);
-    if (res.status === 401) {
-      this.opts.tokenManager.invalidate();
-      res = await this.send(method, path, options);
+    if (res.status === 401 && this.opts.getAccessToken) {
+      res = await this.send(method, path, options, true);
     }
     if (!res.ok) {
       const requestId = res.headers.get("x-request-id") ?? void 0;
       const message = await this.extractMessage(res);
-      throw errorFromResponse(res.status, message, requestId);
+      throw errorFromResponse(
+        res.status,
+        message,
+        requestId,
+        parseRetryAfterMs(res.headers.get("retry-after"))
+      );
     }
     return res;
   }
-  async send(method, path, options) {
-    const token = await this.opts.tokenManager.getToken();
+  async send(method, path, options, forceRefresh = false) {
+    const token = await this.resolveToken(forceRefresh);
     const url = new URL(this.opts.apiBaseUrl + path);
     for (const [k, v] of Object.entries(options.query ?? {})) url.searchParams.set(k, v);
     const headers = {
@@ -235,6 +174,13 @@ var HttpClient = class {
       throw err;
     }
   }
+  async resolveToken(forceRefresh) {
+    const token = this.opts.getAccessToken ? await this.opts.getAccessToken(forceRefresh ? { forceRefresh: true } : void 0) : this.opts.accessToken;
+    if (!token) {
+      throw new DocmanaError("Missing Docmana access token", { code: "auth_missing" });
+    }
+    return token;
+  }
   async extractMessage(res) {
     try {
       const data = await res.clone().json();
@@ -244,8 +190,20 @@ var HttpClient = class {
     }
   }
 };
+function parseRetryAfterMs(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1e3;
+  }
+  const retryAt = Date.parse(value);
+  if (!Number.isNaN(retryAt)) {
+    return Math.max(0, retryAt - Date.now());
+  }
+  return void 0;
+}
 
-// src/files/resolve-input.ts
+// src/sdk/files/resolve-input.ts
 import { readFile } from "fs/promises";
 import { basename } from "path";
 var CONTENT_TYPES = {
@@ -270,310 +228,310 @@ function isReadable(x) {
 function isPathInput(x) {
   return typeof x === "object" && x !== null && typeof x.path === "string";
 }
+function isNamedFileInput(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const value = x;
+  return typeof value.filename === "string" && (value.data instanceof Uint8Array || isReadable(value.data));
+}
 async function streamToBuffer(stream) {
   const chunks = [];
   for await (const chunk of stream) chunks.push(Buffer.from(chunk));
   return Buffer.concat(chunks);
 }
-async function resolveOne(input, fallbackName) {
+function toBlobBytes(bytes) {
+  return new Uint8Array(bytes);
+}
+async function resolveOne(input) {
   if (typeof input === "string" || isPathInput(input)) {
     const path = typeof input === "string" ? input : input.path;
     const data = await readFile(path);
     const filename = basename(path);
-    return { data: new Blob([data]), filename, contentType: contentTypeFor(filename) };
-  }
-  if (input instanceof Uint8Array) {
-    return {
-      data: new Blob([input]),
-      filename: fallbackName,
-      contentType: contentTypeFor(fallbackName)
-    };
+    return { data: new Blob([toBlobBytes(data)]), filename, contentType: contentTypeFor(filename) };
   }
-  if (isReadable(input)) {
-    const buf = await streamToBuffer(input);
+  if (isNamedFileInput(input)) {
+    const bytes = input.data instanceof Uint8Array ? input.data : await streamToBuffer(input.data);
     return {
-      data: new Blob([buf]),
-      filename: fallbackName,
-      contentType: contentTypeFor(fallbackName)
+      data: new Blob([toBlobBytes(bytes)]),
+      filename: input.filename,
+      contentType: input.contentType ?? contentTypeFor(input.filename)
     };
   }
   throw new Error("Unsupported file input type");
 }
 async function resolveInputs(input) {
-  const list = input.files ?? (input.file !== void 0 ? [input.file] : []);
-  if (list.length === 0) throw new Error("runFlow requires `file` or `files`");
-  const fallback = input.fileName ?? "upload.bin";
-  return Promise.all(list.map((item) => resolveOne(item, fallback)));
+  const list = input.files;
+  if (list.length === 0) throw new Error("runFlow requires `files`");
+  return Promise.all(list.map((item) => resolveOne(item)));
 }
 
-// src/api/upload.ts
-async function uploadFiles(http, parts, signal) {
+// src/sdk/api/run-flow.ts
+async function runFlow(http, flowId, parts, signal, useDraftVersion = false, context, callbackUrl, language) {
   const form = new FormData();
   for (const part of parts) {
     form.append("files", new File([part.data], part.filename, { type: part.contentType }));
   }
-  const res = await http.requestJson("POST", "/upload", { body: form, signal });
-  return [res.id];
+  if (context !== void 0) form.append("json_context", JSON.stringify(context));
+  if (callbackUrl !== void 0) form.append("callback_url", callbackUrl);
+  if (language !== void 0) form.append("language", language);
+  if (useDraftVersion) form.append("useDraftVersion", "true");
+  return http.requestJson(
+    "POST",
+    `/flows/${flowId}/execute-async`,
+    { body: form, signal }
+  );
+}
+
+// src/sdk/api/execution-status.ts
+async function getStatus(http, executionResultId, signal) {
+  const res = await http.requestRaw("GET", `/executions/${executionResultId}/status`, { signal });
+  const text = await res.text();
+  const body = text ? JSON.parse(text) : { status: "" };
+  const pollAfterMs = parsePositiveInt(res.headers.get("x-poll-after"));
+  return pollAfterMs === void 0 ? body : { ...body, pollAfterMs };
+}
+function parsePositiveInt(value) {
+  if (!value) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : void 0;
 }
 
-// src/api/run-flow.ts
-async function runFlow(http, flowId, uuidFiles, signal, once = false, context, callbackUrl) {
-  const path = once ? `/flows/run_once_flow/${flowId}` : `/flows/run_flow/${flowId}`;
-  const body = { uuid_files: uuidFiles };
-  if (context !== void 0) body.json_context = context;
-  if (callbackUrl !== void 0) body.callback_url = callbackUrl;
-  const res = await http.requestJson("POST", path, {
-    query: { async_mode: "true" },
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
+// src/sdk/api/execution-result.ts
+async function getResult(http, executionResultId, signal, language) {
+  return http.requestJson("GET", `/executions/${executionResultId}/result`, {
+    query: language ? { language } : void 0,
     signal
   });
-  return res.execution_result_id;
 }
 
-// src/api/execution-status.ts
-async function getStatus(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-status/${executionResultId}`, { signal });
+// src/sdk/api/list-flows.ts
+async function listFlows(http) {
+  const flows = await http.requestJson("GET", "/flows");
+  return Array.isArray(flows) ? flows.map(toFlowListItem) : [];
+}
+function toFlowListItem(flow) {
+  const value = flow && typeof flow === "object" ? flow : {};
+  return {
+    id: toStringValue(value.id),
+    name: toStringValue(value.name),
+    state: toStateValue(value.state)
+  };
+}
+function toStringValue(value) {
+  return typeof value === "string" ? value : "";
+}
+function toStateValue(value) {
+  return typeof value === "string" && value.trim() ? value : "unknown";
+}
+
+// src/sdk/api/list-organizations.ts
+async function listOrganizations(http) {
+  const organizations = await http.requestJson("GET", "/organizations");
+  return Array.isArray(organizations) ? organizations.map(toAccessibleOrganization).filter(isAccessibleOrganization) : [];
+}
+function toAccessibleOrganization(organization) {
+  const value = organization && typeof organization === "object" ? organization : {};
+  const id = toStringValue2(value.id).trim();
+  if (!id) return void 0;
+  const name = toStringValue2(value.name).trim() || id;
+  return {
+    id,
+    name
+  };
+}
+function isAccessibleOrganization(organization) {
+  return organization !== void 0;
+}
+function toStringValue2(value) {
+  return typeof value === "string" ? value : "";
+}
+
+// src/sdk/api/flow-metadata.ts
+async function getFlowMetadata(http, flowId) {
+  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/metadata`);
 }
 
-// src/api/execution-result.ts
-async function getResult(http, executionResultId, signal) {
-  return http.requestJson("GET", `/flows/execution-result/${executionResultId}`, { signal });
+// src/sdk/api/flow-definition.ts
+async function getFlowDefinition(http, flowId) {
+  return http.requestJson("GET", `/flows/${encodeURIComponent(flowId)}/definition`);
+}
+
+// src/sdk/api/organization-documents.ts
+async function listOrganizationDocuments(http, options = {}) {
+  const result = await http.requestJson("GET", "/organization-documents", {
+    query: options.prefix ? { prefix: options.prefix } : void 0
+  });
+  const value = result && typeof result === "object" ? result : {};
+  return {
+    configured: value.configured === true,
+    documents: Array.isArray(value.documents) ? value.documents.map(toOrganizationDocument).filter(isOrganizationDocument) : []
+  };
+}
+async function downloadOrganizationDocument(http, path) {
+  const result = await http.requestBytes("GET", "/organization-documents/download", {
+    query: { path }
+  });
+  return {
+    bytes: result.bytes,
+    filename: filenameFromHeaders(result.headers) ?? filenameFromPath(path),
+    contentType: result.headers.get("content-type") || void 0
+  };
+}
+async function downloadOrganizationDocuments(http, paths) {
+  return Promise.all(paths.map((path) => downloadOrganizationDocument(http, path)));
+}
+function toOrganizationDocument(document) {
+  const value = document && typeof document === "object" ? document : {};
+  const path = toStringValue3(value.path).trim();
+  if (!path) return void 0;
+  const contentType = toStringValue3(value.contentType).trim();
+  return {
+    path,
+    name: toStringValue3(value.name).trim() || filenameFromPath(path),
+    size: toNumberValue(value.size),
+    lastModified: toStringValue3(value.lastModified).trim(),
+    ...contentType ? { contentType } : {}
+  };
+}
+function isOrganizationDocument(document) {
+  return document !== void 0;
+}
+function filenameFromHeaders(headers) {
+  const disposition = headers.get("content-disposition");
+  if (!disposition) return void 0;
+  const utf8 = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
+  if (utf8?.[1]) return decodeURIComponent(utf8[1]);
+  const quoted = /filename="([^"]+)"/i.exec(disposition);
+  if (quoted?.[1]) return quoted[1];
+  const plain = /filename=([^;]+)/i.exec(disposition);
+  return plain?.[1]?.trim();
+}
+function filenameFromPath(path) {
+  return path.replace(/\\/g, "/").split("/").filter(Boolean).pop() || path;
+}
+function toStringValue3(value) {
+  return typeof value === "string" ? value : "";
+}
+function toNumberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
-// src/polling/poll.ts
+// src/sdk/polling/poll.ts
 var TERMINAL = /* @__PURE__ */ new Set(["Completed", "Failed"]);
 var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function pollUntilTerminal(opts) {
   const sleep = opts.sleep ?? defaultSleep;
   const start = Date.now();
   const elapsed = opts.elapsed ?? (() => Date.now() - start);
+  const random = opts.random ?? Math.random;
+  let fallbackAttempt = 0;
   for (; ; ) {
     if (opts.signal?.aborted) throw new DocmanaAbortError("Polling aborted");
-    const status = await opts.check();
+    let result;
+    try {
+      result = normalizePollResult(await opts.check());
+    } catch (err) {
+      if (!(err instanceof DocmanaRateLimitError)) throw err;
+      if (elapsed() >= opts.timeoutMs) {
+        throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
+      }
+      await sleep(err.retryAfterMs ?? opts.intervalMs);
+      continue;
+    }
+    const { status } = result;
     if (TERMINAL.has(status)) return status;
     if (elapsed() >= opts.timeoutMs) {
       throw new DocmanaTimeoutError(`Execution did not finish within ${opts.timeoutMs}ms`);
     }
-    await sleep(opts.intervalMs);
+    const fallbackDelay = fullJitterDelay(
+      opts.intervalMs,
+      opts.maxIntervalMs,
+      fallbackAttempt,
+      random
+    );
+    fallbackAttempt += 1;
+    await sleep(result.nextDelayMs ?? fallbackDelay);
   }
 }
-
-// src/mappers/mapper.ts
-function extractNodeFields(rawNode, targetLanguage) {
-  const metadataFields = /* @__PURE__ */ new Set([
-    "node_id",
-    "node_name",
-    "node_type",
-    "feature_name",
-    "running_time",
-    "status",
-    "score",
-    "feedback",
-    "translations",
-    "tokens",
-    "input_tokens",
-    "output_tokens",
-    "errors",
-    "mana",
-    "model",
-    "tool_calls",
-    "prompt_id",
-    "prompt",
-    "prompt_name",
-    "label",
-    "scoreDescription",
-    "score_description",
-    "result",
-    "documentType"
-  ]);
-  let sourceObj = rawNode;
-  if (targetLanguage) {
-    const translations = rawNode.translations;
-    if (!translations || !translations[targetLanguage]) {
-      throw new DocmanaError(
-        `Translation for language '${targetLanguage}' is missing on node '${rawNode.node_name || rawNode.node_id}'`,
-        { code: "translation_missing", status: 400 }
-      );
-    }
-    sourceObj = translations[targetLanguage];
-  }
-  const dynamicFields = {};
-  for (const [key, value] of Object.entries(sourceObj)) {
-    if (!metadataFields.has(key)) {
-      dynamicFields[key] = value;
-    }
-  }
-  const sdkNode = {
-    status: rawNode.status || "Unknown"
-  };
-  if (rawNode.errors && rawNode.errors.length > 0) {
-    sdkNode.errors = rawNode.errors;
-  }
-  const nodeType = rawNode.node_type || "";
-  const isScoreNode = /^(Validation|Classification|CrossValidation|Conclusion|Finish)$/i.test(
-    nodeType
-  );
-  if (isScoreNode && rawNode.score !== void 0 && rawNode.score !== null) {
-    sdkNode.score = rawNode.score;
-  }
-  const feedback = sourceObj.feedback ?? rawNode.feedback;
-  if (feedback !== void 0 && feedback !== null) {
-    sdkNode.feedback = feedback;
-  }
-  if (Object.keys(dynamicFields).length > 0) {
-    sdkNode.data = dynamicFields;
-  }
-  return sdkNode;
+function normalizePollResult(result) {
+  return typeof result === "string" ? { status: result } : result;
 }
-function mapExecutionResult(raw, targetLanguage) {
-  const sdkResult = {
-    status: raw.status || "Unknown",
-    executionId: String(raw.execution_id || raw.executionResultId || raw.execution_result_id || ""),
-    documents: {
-      mappings: []
-    }
-  };
-  if (raw.errors && raw.errors.length > 0) {
-    sdkResult.errors = raw.errors;
-  }
-  const results = raw.results || [];
-  for (const item of results) {
-    const isDocSpecific = !!item.document;
-    if (isDocSpecific && item.document) {
-      const docReq = item.document;
-      const docKey = docReq.doc_key || "unknown_doc";
-      const docName = docReq.name || "";
-      sdkResult.documents.mappings.push({
-        name: docName,
-        reference: docKey
-      });
-      const docResult = {
-        status: item.status || docReq.status || "Unknown",
-        extractions: {},
-        validations: {}
-      };
-      const nodeResults = item.node_results || [];
-      for (const node of nodeResults) {
-        const nodeType = node.node_type || "";
-        const nodeName = node.node_name || node.node_id || "unknown_node";
-        if (/^Classification$/i.test(nodeType)) {
-          const mappedNode = extractNodeFields(node, targetLanguage);
-          if (!docResult.classifications) {
-            docResult.classifications = {};
-          }
-          docResult.classifications[nodeName] = mappedNode;
-        } else if (/^MetadataExtraction$/i.test(nodeType)) {
-          docResult.metadataExtraction = extractNodeFields(node, targetLanguage);
-        } else if (/^Extraction$/i.test(nodeType)) {
-          if (docResult.extractions) {
-            docResult.extractions[nodeName] = extractNodeFields(node, targetLanguage);
-          }
-        } else if (/^Validation$/i.test(nodeType)) {
-          if (docResult.validations) {
-            docResult.validations[nodeName] = extractNodeFields(node, targetLanguage);
-          }
-        }
-      }
-      if (docResult.extractions && Object.keys(docResult.extractions).length === 0) {
-        delete docResult.extractions;
-      }
-      if (docResult.validations && Object.keys(docResult.validations).length === 0) {
-        delete docResult.validations;
-      }
-      sdkResult.documents[docKey] = docResult;
-    } else {
-      const nodeResults = item.node_results || [];
-      for (const node of nodeResults) {
-        const nodeType = node.node_type || "";
-        const nodeName = node.node_name || node.node_id || "unknown_node";
-        if (/^CrossValidation$/i.test(nodeType)) {
-          if (!sdkResult.crossValidations) {
-            sdkResult.crossValidations = {};
-          }
-          sdkResult.crossValidations[nodeName] = extractNodeFields(
-            node,
-            targetLanguage
-          );
-        } else if (/^(Conclusion|Finish)$/i.test(nodeType)) {
-          if (!sdkResult.conclusions) {
-            sdkResult.conclusions = {};
-          }
-          sdkResult.conclusions[nodeName] = extractNodeFields(
-            node,
-            targetLanguage
-          );
-        }
-      }
-    }
-  }
-  return sdkResult;
+function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
+  const capDelay = Math.min(maxIntervalMs, intervalMs * 2 ** attempt);
+  return Math.round(intervalMs + random() * (capDelay - intervalMs));
 }
 
-// src/client.ts
+// src/sdk/client.ts
 var Docmana = class {
   config;
   http;
   constructor(config) {
     this.config = resolveConfig(config);
-    const tokenManager = new TokenManager({
-      clientId: this.config.clientId,
-      clientSecret: this.config.clientSecret,
-      tokenEndpoint: this.config.tokenEndpoint,
-      scope: this.config.scope,
-      fetchImpl: this.config.fetchImpl,
-      tokenCache: this.config.tokenCache
-    });
     this.http = new HttpClient({
       apiBaseUrl: this.config.apiBaseUrl,
       fetchImpl: this.config.fetchImpl,
-      tokenManager,
+      accessToken: this.config.accessToken,
+      getAccessToken: this.config.getAccessToken,
       headers: this.config.headers
     });
   }
-  async runFlowAsync(flowId, input) {
-    const parts = await resolveInputs(input);
-    const fileIds = await uploadFiles(this.http, parts, input.signal);
-    const executionResultId = await runFlow(
-      this.http,
-      flowId,
-      fileIds,
-      input.signal,
-      input.once ?? false,
-      input.context
-    );
-    return { executionResultId, fileIds };
-  }
-  async runFlowWithCallback(flowId, input) {
-    const parts = await resolveInputs(input);
-    const fileIds = await uploadFiles(this.http, parts, input.signal);
-    const executionResultId = await runFlow(
+  async runFlowAsync(flowId, params, options = {}) {
+    const parts = await resolveInputs(params);
+    return runFlow(
       this.http,
       flowId,
-      fileIds,
-      input.signal,
-      input.once ?? false,
-      input.context,
-      input.callbackUrl
+      parts,
+      options.signal,
+      params.useDraftVersion ?? false,
+      params.context,
+      params.callbackUrl,
+      params.language
     );
-    return { executionResultId, fileIds };
   }
   async getStatus(executionResultId, signal) {
     return getStatus(this.http, executionResultId, signal);
   }
   async getResult(executionResultId, signal, language) {
-    const rawResult = await getResult(this.http, executionResultId, signal);
-    return mapExecutionResult(rawResult, language);
+    return getResult(this.http, executionResultId, signal, language);
   }
-  async runFlow(flowId, input) {
-    const { executionResultId } = await this.runFlowAsync(flowId, input);
+  async runFlow(flowId, params, options = {}) {
+    const { executionResultId } = await this.runFlowAsync(flowId, params, {
+      signal: options.signal
+    });
+    let attempt = 0;
+    const startedAt = Date.now();
     await pollUntilTerminal({
-      check: async () => (await this.getStatus(executionResultId, input.signal)).status,
-      intervalMs: input.pollIntervalMs ?? this.config.pollIntervalMs,
-      timeoutMs: input.timeoutMs ?? this.config.timeoutMs,
-      signal: input.signal
+      check: async () => {
+        attempt += 1;
+        try {
+          const statusResult = await this.getStatus(executionResultId, options.signal);
+          const status = statusResult.status;
+          const nextPollAfterMs = this.isTerminalStatus(status) ? void 0 : statusResult.pollAfterMs;
+          options.onPoll?.({
+            executionResultId,
+            status,
+            attempt,
+            elapsedMs: Date.now() - startedAt,
+            nextPollAfterMs
+          });
+          return { status, nextDelayMs: nextPollAfterMs };
+        } catch (err) {
+          if (err instanceof DocmanaRateLimitError) {
+            options.onRateLimit?.({
+              executionResultId,
+              attempt,
+              elapsedMs: Date.now() - startedAt,
+              retryAfterMs: err.retryAfterMs ?? options.pollIntervalMs ?? this.config.pollIntervalMs
+            });
+          }
+          throw err;
+        }
+      },
+      intervalMs: options.pollIntervalMs ?? this.config.pollIntervalMs,
+      maxIntervalMs: options.pollMaxIntervalMs ?? this.config.pollMaxIntervalMs,
+      timeoutMs: options.timeoutMs ?? this.config.timeoutMs,
+      signal: options.signal
     });
-    const result = await this.getResult(executionResultId, input.signal, input.language);
+    const result = await this.getResult(executionResultId, options.signal, params.language);
     if (result.status === "Failed") {
       throw new DocmanaExecutionError(
         `Flow ${flowId} execution failed`,
@@ -583,9 +541,33 @@ var Docmana = class {
     }
     return result;
   }
+  async listFlows() {
+    return listFlows(this.http);
+  }
+  async listOrganizations() {
+    return listOrganizations(this.http);
+  }
+  async getFlowMetadata(flowId) {
+    return getFlowMetadata(this.http, flowId);
+  }
+  async getFlowDefinition(flowId) {
+    return getFlowDefinition(this.http, flowId);
+  }
+  async listOrganizationDocuments(options = {}) {
+    return listOrganizationDocuments(this.http, options);
+  }
+  async downloadOrganizationDocument(path) {
+    return downloadOrganizationDocument(this.http, path);
+  }
+  async downloadOrganizationDocuments(paths) {
+    return downloadOrganizationDocuments(this.http, paths);
+  }
+  isTerminalStatus(status) {
+    return status === "Completed" || status === "Failed";
+  }
 };
 
-// src/cli.ts
+// src/cli/errors.ts
 var CliUsageError = class extends Error {
   constructor(message) {
     super(message);
@@ -601,226 +583,212 @@ var CliSilentError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
-var HELP = {
-  root: "Run Docmana document-analysis flows.",
-  flow: "Manage and run Docmana flows.",
-  config: "Manage Docmana CLI configuration.",
-  configInit: "Create or update a local Docmana CLI config file.",
-  login: "Acquire and cache a Docmana OAuth2 access token.",
-  run: "Upload documents, run a Docmana flow, wait for completion, and print the result."
-};
-var DEFAULT_CONFIG_FILE = "docmana.config.json";
-var DEFAULT_TOKEN_CACHE_FILE = "docmana.token.json";
-async function runCli(argv = process.argv.slice(2), env = process.env, io = {
-  stdout: (text) => process.stdout.write(text),
-  stderr: (text) => process.stderr.write(text)
-}, clientFactory = (config) => new Docmana(config), deps = {}) {
-  const program = buildProgram(env, io, clientFactory, deps);
-  if (argv.length === 0) {
-    io.stdout(program.helpInformation());
-    return 0;
+
+// src/cli/formatting.ts
+function formatFlowList(flows) {
+  if (flows.length === 0) return "No flows found.\n";
+  const lines = ["Docmana flows"];
+  for (const flow of flows) {
+    const id = flow.id || "(no id)";
+    const name = flow.name || "(no name)";
+    const state = flow.state ? ` [${flow.state}]` : "";
+    lines.push(`- ${id} - ${name}${state}`);
   }
-  try {
-    await program.parseAsync(argv, { from: "user" });
-    return 0;
-  } catch (err) {
-    if (err instanceof CliSilentError) {
-      return err.exitCode;
-    }
-    if (err instanceof CliUsageError) {
-      io.stderr(`Error: ${err.message}
-`);
-      return 2;
-    }
-    if (err instanceof CommanderError) {
-      return err.exitCode === 0 ? 0 : 2;
-    }
-    io.stderr(`${formatRuntimeError(err)}
-`);
-    return 1;
+  return `${lines.join("\n")}
+`;
+}
+function formatOrganizationList(organizations) {
+  if (organizations.length === 0) return "No organizations found.\n";
+  const lines = ["Docmana organizations"];
+  for (const organization of organizations) {
+    const id = organization.id || "(no id)";
+    const name = organization.name || "(no name)";
+    lines.push(`- ${id} - ${name}`);
   }
+  return `${lines.join("\n")}
+`;
 }
-function buildProgram(env, io, clientFactory, deps) {
-  const program = new Command();
-  program.name("docmana").description(HELP.root).showHelpAfterError().configureOutput({
-    writeOut: io.stdout,
-    writeErr: io.stderr,
-    outputError: (str, write) => write(str)
-  }).exitOverride();
-  program.command("login").description(HELP.login).option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (options) => {
-    await loginCommand(options, env, io, deps);
-  });
-  const flow = program.command("flow").description(HELP.flow).action(() => {
-    io.stdout(flow.helpInformation());
-  });
-  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--api-url <url>", "Docmana API base URL; defaults to DOCMANA_API_URL").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--organisation <id>", "Docmana organisation id; defaults to DOCMANA_ORGANISATION").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").action(async (flowId, options) => {
-    await runFlowCommand(flowId, options, env, io, clientFactory, deps);
-  });
-  const config = program.command("config").description(HELP.config).action(() => {
-    io.stdout(config.helpInformation());
-  });
-  config.command("init").description(HELP.configInit).option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).action(async (options) => {
-    await configInitCommand(options, io, deps);
-  });
-  return program;
+function formatOrganizationDocumentList(documents) {
+  if (documents.length === 0) return "No organization documents found.\n";
+  const lines = ["Docmana organization documents"];
+  for (const document of documents) {
+    const contentType = document.contentType ? ` [${document.contentType}]` : "";
+    lines.push(`- ${document.path} - ${document.name} (${document.size} bytes)${contentType}`);
+  }
+  return `${lines.join("\n")}
+`;
 }
-async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
-  try {
-    const files = parseFiles(options.files);
-    const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-    const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-    const clientSecret = firstNonEmpty(
-      options.clientSecret,
-      env.DOCMANA_CLIENT_SECRET,
-      cliConfig.clientSecret
-    );
-    const organisation = firstNonEmpty(
-      options.organisation,
-      env.DOCMANA_ORGANISATION,
-      cliConfig.organisation
-    );
-    const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
-    const tokenEndpoint = firstNonEmpty(
-      options.tokenUrl,
-      env.DOCMANA_TOKEN_URL,
-      cliConfig.tokenEndpoint
-    );
-    const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope);
-    if (!clientId)
-      throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
-    if (!clientSecret) {
-      throw new CliUsageError(
-        "Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET."
-      );
-    }
-    if (!organisation) {
-      throw new CliUsageError("Missing organisation. Use --organisation or DOCMANA_ORGANISATION.");
+function formatHumanResult(result) {
+  const lines = ["Docmana flow completed", `Status: ${String(result.status ?? "Unknown")}`];
+  const executionId = result.executionId;
+  if (executionId) lines.push(`Execution id: ${String(executionId)}`);
+  if (result.documents && result.documents.mappings) {
+    lines.push(`Results: ${result.documents.mappings.length}`);
+  }
+  if (result.errors && result.errors.length > 0) {
+    lines.push(`Errors: ${result.errors.length}`);
+  }
+  const previewData = {};
+  if (result.documents && result.documents.mappings) {
+    for (const mapping of result.documents.mappings.slice(0, 3)) {
+      const docKey = mapping.reference;
+      previewData[mapping.name] = result.documents[docKey];
     }
-    const client = clientFactory({
-      clientId,
-      clientSecret,
-      apiBaseUrl,
-      tokenEndpoint,
-      scope,
-      headers: { "X-Selected-Organization": organisation },
-      tokenCache: createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)))
-    });
-    const result = await client.runFlow(flowId, {
-      files: files.map((path) => ({ path })),
-      language: options.language
-    });
-    if (options.json) {
-      io.stdout(`${JSON.stringify(result, null, 2)}
-`);
-      return;
+  }
+  const preview = formatResultsPreview(previewData);
+  if (preview) lines.push("", "Result preview:", preview);
+  lines.push("", "Use --json to print the complete result payload.");
+  return `${lines.join("\n")}
+`;
+}
+function formatRuntimeError(err) {
+  return formatHumanError(err);
+}
+function formatHumanError(err) {
+  if (err instanceof DocmanaExecutionError) {
+    const lines = [`Error: ${err.message}`];
+    if (err.errors && err.errors.length > 0) {
+      lines.push("Global errors:");
+      for (const e of err.errors) {
+        lines.push(`  - ${formatSingleError(e)}`);
+      }
     }
-    io.stdout(formatHumanResult(result));
-  } catch (err) {
-    if (options.json) {
-      if (err instanceof DocmanaExecutionError && err.result) {
-        io.stdout(`${JSON.stringify(err.result, null, 2)}
-`);
-      } else {
-        const errorPayload = {
-          error: err instanceof Error ? err.message : String(err)
-        };
-        if (err instanceof DocmanaError) {
-          errorPayload.code = err.code;
-          if (err.status !== void 0) errorPayload.status = err.status;
-          if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    const result = err.result;
+    if (result?.documents?.mappings && result.documents.mappings.length > 0) {
+      lines.push("Document execution results:");
+      for (const mapping of result.documents.mappings) {
+        const docKey = mapping.reference;
+        const docName = mapping.name;
+        const docResult = result.documents[docKey];
+        if (!docResult) {
+          lines.push(`  - Document: ${docName} (Status: Unknown)`);
+          continue;
+        }
+        const status = docResult.status || "Unknown";
+        const nodes = [];
+        if (docResult.classifications) nodes.push(...Object.values(docResult.classifications));
+        if (docResult.metadataExtraction) nodes.push(docResult.metadataExtraction);
+        if (docResult.extractions) nodes.push(...Object.values(docResult.extractions));
+        if (docResult.validations) nodes.push(...Object.values(docResult.validations));
+        const hasNodeFailures = nodes.some(
+          (n) => n.status === "Failed" || n.errors && n.errors.length > 0
+        );
+        lines.push(`  - Document: ${docName} (Status: ${status})`);
+        if (docResult.status !== "Failed" && !hasNodeFailures) continue;
+        if (docResult.classifications) {
+          for (const [nodeName, node] of Object.entries(docResult.classifications)) {
+            if (node.errors && node.errors.length > 0) {
+              lines.push(`    Classification: ${nodeName} (Status: ${node.status})`);
+              for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+            }
+          }
+        }
+        if (docResult.metadataExtraction?.errors?.length) {
+          lines.push(`    MetadataExtraction: (Status: ${docResult.metadataExtraction.status})`);
+          for (const nodeErr of docResult.metadataExtraction.errors) {
+            lines.push(`      - ${nodeErr}`);
+          }
+        }
+        if (docResult.extractions) {
+          for (const [nodeName, node] of Object.entries(docResult.extractions)) {
+            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+              lines.push(`    Extraction: ${nodeName} (Status: ${node.status})`);
+              if (node.errors) {
+                for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+              }
+            }
+          }
+        }
+        if (docResult.validations) {
+          for (const [nodeName, node] of Object.entries(docResult.validations)) {
+            if (node.status === "Failed" || node.errors && node.errors.length > 0) {
+              lines.push(`    Validation: ${nodeName} (Status: ${node.status})`);
+              if (node.errors) {
+                for (const nodeErr of node.errors) lines.push(`      - ${nodeErr}`);
+              }
+            }
+          }
         }
-        io.stdout(`${JSON.stringify(errorPayload, null, 2)}
-`);
       }
-      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
     }
-    throw err;
+    return lines.join("\n");
   }
+  if (err instanceof DocmanaError) {
+    return `Error: ${err.message} (Code: ${err.code})`;
+  }
+  if (err instanceof Error) {
+    return `Error: ${err.message}`;
+  }
+  return `Error: ${String(err)}`;
 }
-async function loginCommand(options, env, io, deps) {
-  const auth = await resolveAuthConfig(options, env, deps);
-  const tokenCachePath = resolveTokenCachePath(options.tokenCache, getCwd(deps));
-  const tokenCache = createFileTokenCache(tokenCachePath);
-  const tokenManager = new TokenManager({
-    clientId: auth.clientId,
-    clientSecret: auth.clientSecret,
-    tokenEndpoint: auth.tokenEndpoint,
-    scope: auth.scope,
-    fetchImpl: deps.fetch ?? fetch,
-    tokenCache
-  });
-  await tokenManager.getToken();
-  const cached = await tokenCache.read();
-  io.stdout(`Logged in. Token cached at ${tokenCachePath}
-`);
-  if (cached) io.stdout(formatTokenExpiry(cached.expiresAt));
-}
-function formatTokenExpiry(expiresAt) {
-  const expiresAtDate = new Date(expiresAt);
-  return [
-    `Token expires at local time ${expiresAtDate.toLocaleString()}`,
-    `Token expires at UTC ${expiresAtDate.toISOString()}`
-  ].join("\n") + "\n";
+function formatResultsPreview(results) {
+  if (!results) return void 0;
+  const preview = JSON.stringify(results, null, 2);
+  if (!preview) return void 0;
+  return preview.length > 2e3 ? `${preview.slice(0, 2e3)}
+...` : preview;
 }
-async function resolveAuthConfig(options, env, deps) {
-  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
-  const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
-  const clientSecret = firstNonEmpty(
-    options.clientSecret,
-    env.DOCMANA_CLIENT_SECRET,
-    cliConfig.clientSecret
-  );
-  const tokenEndpoint = firstNonEmpty(options.tokenUrl, env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint;
-  const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope;
-  if (!clientId)
-    throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
-  if (!clientSecret) {
-    throw new CliUsageError("Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET.");
+function formatSingleError(e) {
+  if (typeof e === "string") return e;
+  if (e && typeof e === "object") {
+    const obj = e;
+    if (typeof obj.msg === "string") return obj.msg;
+    if (typeof obj.message === "string") return obj.message;
+    if (typeof obj.error === "string") return obj.error;
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
   }
-  return { clientId, clientSecret, tokenEndpoint, scope };
+  return String(e);
 }
-async function configInitCommand(options, io, deps) {
-  const cwd = getCwd(deps);
-  const configPath = resolveConfigPath(options.config, cwd);
-  const existing = await loadCliConfig(options.config, cwd, false);
-  const defaultPrompt = deps.prompt ? void 0 : createDefaultPrompt();
-  const prompt = deps.prompt ?? defaultPrompt?.prompt;
-  if (!prompt) throw new CliUsageError("Unable to initialize interactive prompt");
-  try {
-    const config = {
-      apiBaseUrl: await prompt("API base URL", {
-        defaultValue: existing.apiBaseUrl ?? DEFAULTS.apiBaseUrl
-      }),
-      tokenEndpoint: await prompt("OAuth2 token endpoint", {
-        defaultValue: existing.tokenEndpoint ?? DEFAULTS.tokenEndpoint
-      }),
-      scope: await prompt("OAuth2 scope", {
-        defaultValue: existing.scope ?? DEFAULTS.scope
-      }),
-      organisation: await prompt("Organisation", {
-        defaultValue: existing.organisation
-      }),
-      clientId: await prompt("Client id", {
-        defaultValue: existing.clientId
-      }),
-      clientSecret: await prompt("Client secret", {
-        defaultValue: existing.clientSecret,
-        secret: true
-      })
-    };
-    await mkdir(dirname(configPath), { recursive: true });
-    await writeFile(configPath, `${JSON.stringify(config, null, 2)}
-`, "utf8");
-    io.stdout(`Wrote ${configPath}
-`);
-    io.stdout(
-      `Warning: ${DEFAULT_CONFIG_FILE} contains credentials and should stay ignored by Git.
-`
-    );
-  } finally {
-    defaultPrompt?.close();
+
+// src/cli/types.ts
+var DEFAULT_CONFIG_FILE = "docmana.config.json";
+var DEFAULT_TOKEN_CACHE_FILE = "docmana.token.json";
+var HELP = {
+  root: "Run Docmana document-analysis flows.",
+  flow: "Manage and run Docmana flows.",
+  organization: "Manage Docmana organizations.",
+  organizationDocument: "Manage organization documents.",
+  config: "Manage Docmana CLI configuration.",
+  configInit: "Create or update a local Docmana CLI config file.",
+  login: "Acquire and cache a Docmana OAuth2 access token.",
+  run: "Upload documents, run a Docmana flow, wait for completion, and print the result.",
+  list: "List Docmana flows available to the Bearer token.",
+  metadata: "Print Docmana flow runtime metadata as JSON.",
+  definition: "Print Docmana flow definition as JSON.",
+  organizationList: "List Docmana organizations available to the Bearer token.",
+  organizationDocumentList: "List organization documents available to the Bearer token.",
+  organizationDocumentDownload: "Download an organization document."
+};
+
+// src/cli/config-store.ts
+import { existsSync } from "fs";
+import { mkdir, readFile as readFile2, rm, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { createInterface } from "readline/promises";
+
+// src/cli/utils.ts
+function getCwd(deps) {
+  return deps.cwd ?? process.cwd();
+}
+function firstNonEmpty(...values) {
+  return values.map((value) => value?.trim()).find(Boolean);
+}
+function parseFiles(filesCsv) {
+  const files = filesCsv?.split(",").map((file) => file.trim()).filter(Boolean) ?? [];
+  if (files.length === 0) {
+    throw new CliUsageError("Missing files. Use --files <path[,path]>.");
   }
+  return files;
+}
+function formatElapsedSeconds(elapsedMs) {
+  return `${Math.floor(elapsedMs / 1e3)}s`;
 }
+
+// src/cli/config-store.ts
 async function loadCliConfig(configPathOption, cwd, requireExisting) {
   const configPath = resolveConfigPath(configPathOption, cwd);
   if (!existsSync(configPath)) {
@@ -848,23 +816,16 @@ function normalizeCliConfig(config) {
     apiBaseUrl: stringValue(config.apiBaseUrl),
     tokenEndpoint: stringValue(config.tokenEndpoint),
     scope: stringValue(config.scope),
-    organisation: stringValue(config.organisation),
     clientId: stringValue(config.clientId),
     clientSecret: stringValue(config.clientSecret)
   };
 }
-function stringValue(value) {
-  return typeof value === "string" && value.trim() ? value : void 0;
-}
 function resolveConfigPath(configPathOption, cwd) {
   return resolve(cwd, configPathOption ?? DEFAULT_CONFIG_FILE);
 }
 function resolveTokenCachePath(tokenCachePathOption, cwd) {
   return resolve(cwd, tokenCachePathOption ?? DEFAULT_TOKEN_CACHE_FILE);
 }
-function getCwd(deps) {
-  return deps.cwd ?? process.cwd();
-}
 function createFileTokenCache(path) {
   return {
     async read() {
@@ -897,6 +858,11 @@ function createFileTokenCache(path) {
     }
   };
 }
+async function writeCliConfig(configPath, config) {
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`, "utf8");
+}
 function createDefaultPrompt() {
   if (!process.stdin.isTTY) {
     let index = 0;
@@ -920,6 +886,9 @@ function createDefaultPrompt() {
     close: () => rl.close()
   };
 }
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
 function formatPrompt(label, options) {
   const defaultHint = options.defaultValue && !options.secret ? ` [${options.defaultValue}]` : options.defaultValue && options.secret ? " [current value hidden]" : "";
   return `${label}${defaultHint}: `;
@@ -929,157 +898,515 @@ async function readStdinLines() {
   for await (const chunk of process.stdin) input += String(chunk);
   return input.split(/\r?\n/);
 }
-function parseFiles(filesCsv) {
-  const files = filesCsv?.split(",").map((file) => file.trim()).filter(Boolean) ?? [];
-  if (files.length === 0) throw new CliUsageError("Missing files. Use --files <path[,path]>.");
-  return files;
-}
-function firstNonEmpty(...values) {
-  return values.map((value) => value?.trim()).find(Boolean);
-}
-function formatHumanResult(result) {
-  const lines = ["Docmana flow completed", `Status: ${String(result.status ?? "Unknown")}`];
-  const executionId = result.executionId;
-  if (executionId) lines.push(`Execution id: ${String(executionId)}`);
-  if (result.documents && result.documents.mappings) {
-    lines.push(`Results: ${result.documents.mappings.length}`);
+
+// src/cli/commands/config-init.ts
+async function configInitCommand(options, io, deps) {
+  const cwd = getCwd(deps);
+  const configPath = resolveConfigPath(options.config, cwd);
+  const existing = await loadCliConfig(options.config, cwd, false);
+  const defaultPrompt = deps.prompt ? void 0 : createDefaultPrompt();
+  const prompt = deps.prompt ?? defaultPrompt?.prompt;
+  if (!prompt) throw new CliUsageError("Unable to initialize interactive prompt");
+  try {
+    const config = {
+      apiBaseUrl: await prompt("API base URL", {
+        defaultValue: existing.apiBaseUrl
+      }),
+      tokenEndpoint: await prompt("OAuth2 token endpoint", {
+        defaultValue: existing.tokenEndpoint ?? DEFAULTS.tokenEndpoint
+      }),
+      scope: await prompt("OAuth2 scope", {
+        defaultValue: existing.scope ?? DEFAULTS.scope
+      }),
+      clientId: await prompt("Client id", {
+        defaultValue: existing.clientId
+      }),
+      clientSecret: await prompt("Client secret", {
+        defaultValue: existing.clientSecret,
+        secret: true
+      })
+    };
+    await writeCliConfig(configPath, config);
+    io.stdout(`Wrote ${configPath}
+`);
+    io.stdout(
+      `Warning: ${DEFAULT_CONFIG_FILE} contains credentials and should stay ignored by Git.
+`
+    );
+  } finally {
+    defaultPrompt?.close();
   }
-  if (result.errors && result.errors.length > 0) {
-    lines.push(`Errors: ${result.errors.length}`);
+}
+
+// src/cli/auth/token-manager.ts
+var SAFETY_MARGIN_MS = 6e4;
+var TokenManager = class {
+  constructor(opts) {
+    this.opts = opts;
   }
-  const previewData = {};
-  if (result.documents && result.documents.mappings) {
-    for (const mapping of result.documents.mappings.slice(0, 3)) {
-      const docKey = mapping.reference;
-      previewData[mapping.name] = result.documents[docKey];
+  opts;
+  token = null;
+  expiresAt = 0;
+  inflight = null;
+  invalidate() {
+    this.token = null;
+    this.expiresAt = 0;
+    void this.opts.tokenCache?.clear().catch(() => void 0);
+  }
+  async getToken() {
+    if (this.token && Date.now() < this.expiresAt) return this.token;
+    const cached = await this.readCachedToken();
+    if (cached) return cached;
+    if (this.inflight) return this.inflight;
+    this.inflight = this.acquire().finally(() => {
+      this.inflight = null;
+    });
+    return this.inflight;
+  }
+  async acquire() {
+    const body = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.opts.clientId,
+      client_secret: this.opts.clientSecret,
+      scope: this.opts.scope
+    });
+    const res = await this.opts.fetchImpl(this.opts.tokenEndpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    if (!res.ok) {
+      throw new DocmanaAuthError("Failed to acquire Docmana access token", { status: res.status });
+    }
+    const json = await res.json();
+    if (typeof json.access_token !== "string" || json.access_token.length === 0 || typeof json.expires_in !== "number" || !Number.isFinite(json.expires_in)) {
+      throw new DocmanaAuthError("Malformed token response from Docmana CIAM", {
+        status: res.status
+      });
     }
+    this.token = json.access_token;
+    this.expiresAt = Date.now() + json.expires_in * 1e3 - SAFETY_MARGIN_MS;
+    await this.writeCachedToken().catch(() => void 0);
+    return this.token;
   }
-  const preview = formatResultsPreview(previewData);
-  if (preview) lines.push("", "Result preview:", preview);
-  lines.push("", "Use --json to print the complete result payload.");
-  return `${lines.join("\n")}
-`;
+  async readCachedToken() {
+    if (!this.opts.tokenCache) return null;
+    let entry;
+    try {
+      entry = await this.opts.tokenCache.read();
+    } catch {
+      return null;
+    }
+    if (!entry) return null;
+    if (entry.clientId !== this.opts.clientId || entry.tokenEndpoint !== this.opts.tokenEndpoint || entry.scope !== this.opts.scope || Date.now() >= entry.expiresAt) {
+      await this.opts.tokenCache.clear().catch(() => void 0);
+      return null;
+    }
+    this.token = entry.accessToken;
+    this.expiresAt = entry.expiresAt;
+    return this.token;
+  }
+  async writeCachedToken() {
+    if (!this.opts.tokenCache || !this.token) return;
+    await this.opts.tokenCache.write({
+      accessToken: this.token,
+      expiresAt: this.expiresAt,
+      clientId: this.opts.clientId,
+      tokenEndpoint: this.opts.tokenEndpoint,
+      scope: this.opts.scope
+    });
+  }
+};
+
+// src/cli/auth/access-token.ts
+async function resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io) {
+  const cached = await readFreshCachedToken(tokenCache);
+  if (cached) return cached;
+  const clientId = firstNonEmpty(env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+  const clientSecret = firstNonEmpty(env.DOCMANA_CLIENT_SECRET, cliConfig.clientSecret);
+  if (!clientId || !clientSecret) {
+    throw new CliUsageError(
+      "Missing access token. Use --access-token, DOCMANA_ACCESS_TOKEN, docmana login, or configure OAuth credentials."
+    );
+  }
+  const tokenManager = new TokenManager({
+    clientId,
+    clientSecret,
+    tokenEndpoint: firstNonEmpty(env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint,
+    scope: firstNonEmpty(env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope,
+    fetchImpl: deps.fetch ?? fetch,
+    tokenCache
+  });
+  const token = await tokenManager.getToken();
+  io.stderr("Generated new access token and updated the token cache.\n");
+  return token;
 }
-function formatResultsPreview(results) {
-  if (!results) return void 0;
-  const preview = JSON.stringify(results, null, 2);
-  if (!preview) return void 0;
-  return preview.length > 2e3 ? `${preview.slice(0, 2e3)}
-...` : preview;
+async function readFreshCachedToken(tokenCache) {
+  const cached = await tokenCache.read().catch(() => null);
+  if (!cached || Date.now() >= cached.expiresAt) return void 0;
+  return cached.accessToken;
 }
-function formatRuntimeError(err) {
-  return formatHumanError(err);
+async function resolveAuthConfig(options, env, deps) {
+  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
+  const clientId = firstNonEmpty(options.clientId, env.DOCMANA_CLIENT_ID, cliConfig.clientId);
+  const clientSecret = firstNonEmpty(
+    options.clientSecret,
+    env.DOCMANA_CLIENT_SECRET,
+    cliConfig.clientSecret
+  );
+  const tokenEndpoint = firstNonEmpty(options.tokenUrl, env.DOCMANA_TOKEN_URL, cliConfig.tokenEndpoint) ?? DEFAULTS.tokenEndpoint;
+  const scope = firstNonEmpty(options.scope, env.DOCMANA_SCOPE, cliConfig.scope) ?? DEFAULTS.scope;
+  if (!clientId) {
+    throw new CliUsageError("Missing client id. Use --client-id or DOCMANA_CLIENT_ID.");
+  }
+  if (!clientSecret) {
+    throw new CliUsageError("Missing client secret. Use --client-secret or DOCMANA_CLIENT_SECRET.");
+  }
+  return { clientId, clientSecret, tokenEndpoint, scope };
 }
-function formatHumanError(err) {
-  if (err instanceof DocmanaExecutionError) {
-    const lines = [`Error: ${err.message}`];
-    if (err.errors && err.errors.length > 0) {
-      lines.push("Global errors:");
-      for (const e of err.errors) {
-        lines.push(`  - ${formatSingleError(e)}`);
+
+// src/cli/commands/api-client.ts
+async function resolveApiClient(options, env, io, clientFactory, deps) {
+  const cliConfig = await loadCliConfig(options.config, getCwd(deps), Boolean(options.config));
+  const apiBaseUrl = firstNonEmpty(options.apiUrl, env.DOCMANA_API_URL, cliConfig.apiBaseUrl);
+  if (!apiBaseUrl) {
+    throw new CliUsageError("Missing API base URL. Use --api-url or DOCMANA_API_URL.");
+  }
+  const tokenCache = createFileTokenCache(resolveTokenCachePath(options.tokenCache, getCwd(deps)));
+  const accessToken = firstNonEmpty(options.accessToken, env.DOCMANA_ACCESS_TOKEN) ?? await resolveFlowAccessToken(env, cliConfig, tokenCache, deps, io);
+  return clientFactory({ apiBaseUrl, accessToken });
+}
+
+// src/cli/commands/flow-definition.ts
+async function flowDefinitionCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const definition = await client.getFlowDefinition(flowId);
+    io.stdout(`${JSON.stringify(definition, null, 2)}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/flow-list.ts
+async function listFlowsCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const flows = await client.listFlows();
+    if (options.json) {
+      io.stdout(`${JSON.stringify(flows, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatFlowList(flows));
+  } catch (err) {
+    if (options.json) {
+      const errorPayload = {
+        error: err instanceof Error ? err.message : String(err)
+      };
+      if (err instanceof DocmanaError) {
+        errorPayload.code = err.code;
+        if (err.status !== void 0) errorPayload.status = err.status;
+        if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
       }
+      io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
     }
-    const result = err.result;
-    if (result) {
-      if (result.documents && result.documents.mappings && result.documents.mappings.length > 0) {
-        lines.push("Document execution results:");
-        for (const mapping of result.documents.mappings) {
-          const docKey = mapping.reference;
-          const docName = mapping.name;
-          const docResult = result.documents[docKey];
-          if (docResult) {
-            const status = docResult.status || "Unknown";
-            const nodes = [];
-            if (docResult.classifications) nodes.push(...Object.values(docResult.classifications));
-            if (docResult.metadataExtraction) nodes.push(docResult.metadataExtraction);
-            if (docResult.extractions) nodes.push(...Object.values(docResult.extractions));
-            if (docResult.validations) nodes.push(...Object.values(docResult.validations));
-            const hasNodeFailures = nodes.some(
-              (n) => n.status === "Failed" || n.errors && n.errors.length > 0
-            );
-            if (docResult.status === "Failed" || hasNodeFailures) {
-              lines.push(`  - Document: ${docName} (Status: ${status})`);
-              if (docResult.classifications) {
-                for (const [nodeName, node] of Object.entries(docResult.classifications)) {
-                  if (node.errors && node.errors.length > 0) {
-                    lines.push(`    Classification: ${nodeName} (Status: ${node.status})`);
-                    for (const nodeErr of node.errors) {
-                      lines.push(`      - ${nodeErr}`);
-                    }
-                  }
-                }
-              }
-              if (docResult.metadataExtraction?.errors && docResult.metadataExtraction.errors.length > 0) {
-                lines.push(
-                  `    MetadataExtraction: (Status: ${docResult.metadataExtraction.status})`
-                );
-                for (const nodeErr of docResult.metadataExtraction.errors) {
-                  lines.push(`      - ${nodeErr}`);
-                }
-              }
-              if (docResult.extractions) {
-                for (const [nodeName, node] of Object.entries(docResult.extractions)) {
-                  if (node.status === "Failed" || node.errors && node.errors.length > 0) {
-                    lines.push(`    Extraction: ${nodeName} (Status: ${node.status})`);
-                    if (node.errors) {
-                      for (const nodeErr of node.errors) {
-                        lines.push(`      - ${nodeErr}`);
-                      }
-                    }
-                  }
-                }
-              }
-              if (docResult.validations) {
-                for (const [nodeName, node] of Object.entries(docResult.validations)) {
-                  if (node.status === "Failed" || node.errors && node.errors.length > 0) {
-                    lines.push(`    Validation: ${nodeName} (Status: ${node.status})`);
-                    if (node.errors) {
-                      for (const nodeErr of node.errors) {
-                        lines.push(`      - ${nodeErr}`);
-                      }
-                    }
-                  }
-                }
-              }
-            } else {
-              lines.push(`  - Document: ${docName} (Status: ${status})`);
-            }
-          } else {
-            lines.push(`  - Document: ${docName} (Status: Unknown)`);
-          }
-        }
+    throw err;
+  }
+}
+
+// src/cli/commands/flow-metadata.ts
+async function flowMetadataCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const metadata = await client.getFlowMetadata(flowId);
+    io.stdout(`${JSON.stringify(metadata, null, 2)}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/organization-document-download.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join } from "path";
+async function organizationDocumentDownloadCommand(path, options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const document = await client.downloadOrganizationDocument(path);
+    const outputPath = options.output ?? join(getCwd(deps), path);
+    await mkdir2(dirname2(outputPath), { recursive: true });
+    await writeFile2(outputPath, document.bytes);
+    io.stdout(`Downloaded ${document.filename} to ${outputPath}
+`);
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/organization-document-list.ts
+async function organizationDocumentListCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const payload = await client.listOrganizationDocuments({ prefix: options.prefix });
+    if (options.json) {
+      io.stdout(`${JSON.stringify(payload, null, 2)}
+`);
+      return;
+    }
+    if (!payload.configured) {
+      io.stdout("Organization document depot is not configured.\n");
+      return;
+    }
+    io.stdout(formatOrganizationDocumentList(payload.documents));
+  } catch (err) {
+    const errorPayload = {
+      error: err instanceof Error ? err.message : String(err)
+    };
+    if (err instanceof DocmanaError) {
+      errorPayload.code = err.code;
+      if (err.status !== void 0) errorPayload.status = err.status;
+      if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+    }
+    io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+    throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+  }
+}
+
+// src/cli/commands/organization-list.ts
+async function listOrganizationsCommand(options, env, io, clientFactory, deps) {
+  try {
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const organizations = await client.listOrganizations();
+    if (options.json) {
+      io.stdout(`${JSON.stringify(organizations, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatOrganizationList(organizations));
+  } catch (err) {
+    if (options.json) {
+      const errorPayload = {
+        error: err instanceof Error ? err.message : String(err)
+      };
+      if (err instanceof DocmanaError) {
+        errorPayload.code = err.code;
+        if (err.status !== void 0) errorPayload.status = err.status;
+        if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
       }
+      io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
     }
-    return lines.join("\n");
+    throw err;
   }
-  if (err instanceof DocmanaError) {
-    return `Error: ${err.message} (Code: ${err.code})`;
+}
+
+// src/cli/commands/flow-run.ts
+async function runFlowCommand(flowId, options, env, io, clientFactory, deps) {
+  try {
+    const files = parseFiles(options.files);
+    const client = await resolveApiClient(options, env, io, clientFactory, deps);
+    const result = await client.runFlow(
+      flowId,
+      {
+        files: files.map((path) => ({ path })),
+        language: options.language,
+        useDraftVersion: options.draft === true
+      },
+      {
+        onPoll: (event) => {
+          const nextPoll = event.nextPollAfterMs === void 0 ? "" : `, next poll in ${formatElapsedSeconds(event.nextPollAfterMs)}`;
+          io.stderr(
+            `Polling execution ${event.executionResultId}: ${event.status} (attempt ${event.attempt}, elapsed ${formatElapsedSeconds(event.elapsedMs)}${nextPoll})
+`
+          );
+        },
+        onRateLimit: (event) => {
+          io.stderr(
+            `Polling execution ${event.executionResultId}: rate limited (attempt ${event.attempt}, retrying in ${formatElapsedSeconds(event.retryAfterMs)})
+`
+          );
+        }
+      }
+    );
+    if (options.json) {
+      io.stdout(`${JSON.stringify(result, null, 2)}
+`);
+      return;
+    }
+    io.stdout(formatHumanResult(result));
+  } catch (err) {
+    if (options.json) {
+      if (err instanceof DocmanaExecutionError && err.result) {
+        io.stdout(`${JSON.stringify(err.result, null, 2)}
+`);
+      } else {
+        const errorPayload = {
+          error: err instanceof Error ? err.message : String(err)
+        };
+        if (err instanceof DocmanaError) {
+          errorPayload.code = err.code;
+          if (err.status !== void 0) errorPayload.status = err.status;
+          if (err.requestId !== void 0) errorPayload.requestId = err.requestId;
+        }
+        io.stdout(`${JSON.stringify(errorPayload, null, 2)}
+`);
+      }
+      throw new CliSilentError(err instanceof CliUsageError ? 2 : 1);
+    }
+    throw err;
   }
-  if (err instanceof Error) {
-    return `Error: ${err.message}`;
+}
+
+// src/cli/commands/login.ts
+async function loginCommand(options, env, io, deps) {
+  const auth = await resolveAuthConfig(options, env, deps);
+  const tokenCachePath = resolveTokenCachePath(options.tokenCache, getCwd(deps));
+  const tokenCache = createFileTokenCache(tokenCachePath);
+  const hadFreshCachedToken = Boolean(await readFreshCachedToken(tokenCache));
+  const tokenManager = new TokenManager({
+    clientId: auth.clientId,
+    clientSecret: auth.clientSecret,
+    tokenEndpoint: auth.tokenEndpoint,
+    scope: auth.scope,
+    fetchImpl: deps.fetch ?? fetch,
+    tokenCache
+  });
+  await tokenManager.getToken();
+  const cached = await tokenCache.read();
+  if (!hadFreshCachedToken) {
+    io.stdout("Generated new access token and updated the token cache.\n");
   }
-  return `Error: ${String(err)}`;
+  io.stdout(`Logged in. Token cached at ${tokenCachePath}
+`);
+  if (cached) io.stdout(formatTokenExpiry(cached.expiresAt));
 }
-function formatSingleError(e) {
-  if (typeof e === "string") return e;
-  if (e && typeof e === "object") {
-    const obj = e;
-    if (typeof obj.msg === "string") return obj.msg;
-    if (typeof obj.message === "string") return obj.message;
-    if (typeof obj.error === "string") return obj.error;
-    try {
-      return JSON.stringify(e);
-    } catch {
-      return String(e);
+function formatTokenExpiry(expiresAt) {
+  const expiresAtDate = new Date(expiresAt);
+  return [
+    `Token expires at local time ${expiresAtDate.toLocaleString()}`,
+    `Token expires at UTC ${expiresAtDate.toISOString()}`
+  ].join("\n") + "\n";
+}
+
+// src/cli/cli.ts
+async function runCli(argv = process.argv.slice(2), env = process.env, io = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text)
+}, clientFactory = (config) => new Docmana(config), deps = {}) {
+  const program = buildProgram(env, io, clientFactory, deps);
+  if (argv.length === 0) {
+    io.stdout(program.helpInformation());
+    return 0;
+  }
+  try {
+    await program.parseAsync(argv, { from: "user" });
+    return 0;
+  } catch (err) {
+    if (err instanceof CliSilentError) {
+      return err.exitCode;
+    }
+    if (err instanceof CliUsageError) {
+      io.stderr(`Error: ${err.message}
+`);
+      return 2;
+    }
+    if (err instanceof CommanderError) {
+      return err.exitCode === 0 ? 0 : 2;
     }
+    io.stderr(`${formatRuntimeError(err)}
+`);
+    return 1;
   }
-  return String(e);
+}
+function buildProgram(env, io, clientFactory, deps) {
+  const program = new Command();
+  program.name("docmana").description(HELP.root).showHelpAfterError().configureOutput({
+    writeOut: io.stdout,
+    writeErr: io.stderr,
+    outputError: (str, write) => write(str)
+  }).exitOverride();
+  program.command("login").description(HELP.login).option("--client-id <id>", "OAuth2 client id; defaults to DOCMANA_CLIENT_ID").option("--client-secret <secret>", "OAuth2 client secret; defaults to DOCMANA_CLIENT_SECRET").option("--token-url <url>", "OAuth2 token endpoint; defaults to DOCMANA_TOKEN_URL").option("--scope <scope>", "OAuth2 scope; defaults to DOCMANA_SCOPE").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (options) => {
+    await loginCommand(options, env, io, deps);
+  });
+  const flow = program.command("flow").description(HELP.flow).action(() => {
+    io.stdout(flow.helpInformation());
+  });
+  flow.command("list").description(HELP.list).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON flow list").action(async (options) => {
+    await listFlowsCommand(options, env, io, clientFactory, deps);
+  });
+  flow.command("run").description(HELP.run).argument("<flow-id>", "Docmana flow id").requiredOption("--files <csv>", "Comma-separated file paths to upload").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON result").option("--language <lang>", "Translate output to specified language").option("--draft", "Run the current draft flow version").action(async (flowId, options) => {
+    await runFlowCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  flow.command("metadata").description(HELP.metadata).argument("<flow-id>", "Docmana flow id").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (flowId, options) => {
+    await flowMetadataCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  flow.command("definition").description(HELP.definition).argument("<flow-id>", "Docmana flow id").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (flowId, options) => {
+    await flowDefinitionCommand(flowId, options, env, io, clientFactory, deps);
+  });
+  const organization = program.command("organization").description(HELP.organization).action(() => {
+    io.stdout(organization.helpInformation());
+  });
+  organization.command("list").description(HELP.organizationList).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--json", "Print the raw JSON organization list").action(async (options) => {
+    await listOrganizationsCommand(options, env, io, clientFactory, deps);
+  });
+  const organizationDocument = organization.command("document").description(HELP.organizationDocument).action(() => {
+    io.stdout(organizationDocument.helpInformation());
+  });
+  organizationDocument.command("list").description(HELP.organizationDocumentList).option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).option("--prefix <prefix>", "Filter documents by path prefix").option("--json", "Print the raw JSON organization document list").action(async (options) => {
+    await organizationDocumentListCommand(options, env, io, clientFactory, deps);
+  });
+  organizationDocument.command("download").description(HELP.organizationDocumentDownload).argument("<path>", "Organization document path").option("--output <file>", "Output file path; defaults to ./{path}").option("--api-url <url>", "Consumer API base URL; defaults to DOCMANA_API_URL").option("--access-token <token>", "Bearer token; defaults to DOCMANA_ACCESS_TOKEN").option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).option("--token-cache <path>", `Token cache path; defaults to ./${DEFAULT_TOKEN_CACHE_FILE}`).action(async (path, options) => {
+    await organizationDocumentDownloadCommand(path, options, env, io, clientFactory, deps);
+  });
+  const config = program.command("config").description(HELP.config).action(() => {
+    io.stdout(config.helpInformation());
+  });
+  config.command("init").description(HELP.configInit).option("--config <path>", `Config file path; defaults to ./${DEFAULT_CONFIG_FILE}`).action(async (options) => {
+    await configInitCommand(options, io, deps);
+  });
+  return program;
 }
 function isDirectRun() {
   const entry = process.argv[1];
   if (!entry) return false;
   try {
-    return realpathSync(resolve(entry)) === realpathSync(fileURLToPath(import.meta.url));
+    return realpathSync(resolve2(entry)) === realpathSync(fileURLToPath(import.meta.url));
   } catch {
     return false;
   }