postgresai 0.16.0-dev.1 → 0.16.0-dev.11

package/dist/bin/postgres-ai.js

@@ -6,43 +6,25 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-function __accessProp(key) {
-  return this[key];
-}
-var __toESMCache_node;
-var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
-  var canCache = mod != null && typeof mod === "object";
-  if (canCache) {
-    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
-    var cached = cache.get(mod);
-    if (cached)
-      return cached;
-  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
+        get: () => mod[key],
         enumerable: true
       });
-  if (canCache)
-    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1020,7 +1002,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;
@@ -13106,7 +13088,7 @@ var require_formats = __commonJS((exports) => {
   }
   var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
   function getTime(strictTimeZone) {
-    return function time3(str2) {
+    return function time(str2) {
       const matches = TIME.exec(str2);
       if (!matches)
         return false;
@@ -13323,43 +13305,92 @@ var require_dist2 = __commonJS((exports, module) => {
 var exports_util2 = {};
 __export(exports_util2, {
   resolveBaseUrls: () => resolveBaseUrls2,
+  requestTimeoutSignal: () => requestTimeoutSignal2,
+  redactTextSecrets: () => redactTextSecrets2,
+  redactSecretsForLog: () => redactSecretsForLog2,
+  redactSecrets: () => redactSecrets2,
   normalizeBaseUrl: () => normalizeBaseUrl2,
   maskSecret: () => maskSecret2,
-  formatHttpError: () => formatHttpError2
+  isRetryableHttpStatus: () => isRetryableHttpStatus2,
+  isFetchTimeout: () => isFetchTimeout2,
+  formatHttpError: () => formatHttpError2,
+  describeFetchError: () => describeFetchError2,
+  HttpStatusError: () => HttpStatusError2,
+  HttpRequestTimeoutError: () => HttpRequestTimeoutError2,
+  DEFAULT_HTTP_REQUEST_TIMEOUT_MS: () => DEFAULT_HTTP_REQUEST_TIMEOUT_MS2
 });
 function isHtmlContent2(text) {
   const trimmed = text.trim();
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
-function formatHttpError2(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES2[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+function formatHttpError2(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES2[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT2}` : "";
-  if (responseBody) {
-    if (isHtmlContent2(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  let bodyCode;
+  let bodyHint;
+  if (responseBody && !isHtmlContent2(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = redactTextSecrets2(message.trim());
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = redactTextSecrets2(details.trim());
+      }
+      if (typeof errObj.code === "string" && errObj.code.trim().length > 0) {
+        bodyCode = errObj.code.trim();
+      }
+      if (typeof errObj.hint === "string" && errObj.hint.trim().length > 0) {
+        bodyHint = redactTextSecrets2(errObj.hint.trim());
+      }
+      if (bodyMessage === undefined && bodyDetails === undefined && bodyCode === undefined && bodyHint === undefined) {
+        bodyDetails = redactSecretsForLog2(JSON.stringify(errObj));
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = redactTextSecrets2(trimmed);
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES2[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const safeReasonPhrase = reasonPhrase ? redactTextSecrets2(reasonPhrase) : undefined;
+  const headline = bodyMessage ?? safeReasonPhrase ?? generic;
+  const codeSuffix = bodyCode && !headline.includes(bodyCode) ? ` (${bodyCode})` : "";
+  let errMsg = `${operation}: HTTP ${status} - ${headline}${codeSuffix}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
+  if (bodyHint) {
+    errMsg += `
+Hint: ${bodyHint}`;
+  }
   return errMsg + remediation;
 }
+function describeFetchError2(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
+function isRetryableHttpStatus2(status) {
+  return status >= 500 || status === 429;
+}
+function requestTimeoutSignal2(timeoutMs) {
+  const requested = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_HTTP_REQUEST_TIMEOUT_MS2;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS2, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
+function isFetchTimeout2(err) {
+  const name = err?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
 function maskSecret2(secret) {
   if (!secret)
     return "";
@@ -13369,6 +13400,35 @@ function maskSecret2(secret) {
     return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
   return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
 }
+function isSensitiveLogKey2(key) {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+  return /^(?:password|passwd|db_(?:pass|password)|conn_?str|secret|token|api_key|private_key|access_key|access_token|refresh_token|auth|auth_key|auth_token|authorization|credentials?|dsn)$/.test(normalized);
+}
+function redactSecrets2(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets2);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = isSensitiveLogKey2(key) && child != null ? "[REDACTED]" : redactSecrets2(child);
+    }
+    return out;
+  }
+  return value;
+}
+function redactSecretsForLog2(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return redactTextSecrets2(text);
+  }
+  return JSON.stringify(redactSecrets2(parsed));
+}
+function redactTextSecrets2(text) {
+  return text.replace(TEXT_URL_USERINFO2, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR2, "$1[REDACTED]");
+}
 function normalizeBaseUrl2(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -13391,7 +13451,7 @@ function resolveBaseUrls2(opts, cfg, defaults2 = {}) {
     storageBaseUrl: normalizeBaseUrl2(storageCandidate)
   };
 }
-var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
+var HTTP_STATUS_MESSAGES2, AUTH_REMEDIATION_HINT2 = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.", STANDARD_REASON_PHRASES2, HttpStatusError2, DEFAULT_HTTP_REQUEST_TIMEOUT_MS2 = 25000, HttpRequestTimeoutError2, TEXT_URL_USERINFO2, TEXT_SENSITIVE_PAIR2;
 var init_util = __esm(() => {
   HTTP_STATUS_MESSAGES2 = {
     400: "Bad Request",
@@ -13405,6 +13465,36 @@ var init_util = __esm(() => {
     503: "Service Unavailable - server temporarily unavailable",
     504: "Gateway Timeout - server temporarily unavailable"
   };
+  STANDARD_REASON_PHRASES2 = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    408: "Request Timeout",
+    409: "Conflict",
+    413: "Payload Too Large",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout"
+  };
+  HttpStatusError2 = class HttpStatusError2 extends Error {
+    status;
+    constructor(message, status) {
+      super(message);
+      this.name = "HttpStatusError";
+      this.status = status;
+    }
+  };
+  HttpRequestTimeoutError2 = class HttpRequestTimeoutError2 extends Error {
+    constructor(operation, timeoutMs) {
+      super(`${operation}: request timed out after ${timeoutMs}ms`);
+      this.name = "HttpRequestTimeoutError";
+    }
+  };
+  TEXT_URL_USERINFO2 = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+  TEXT_SENSITIVE_PAIR2 = /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
 });
 
 // node_modules/commander/esm.mjs
@@ -13425,7 +13515,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.16.0-dev.1",
+  version: "0.16.0-dev.11",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16256,7 +16346,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.16.0-dev.1";
+var version = "0.16.0-dev.11";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16398,35 +16488,105 @@ function isHtmlContent(text) {
   return trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html") || trimmed.startsWith("<HTML");
 }
 var AUTH_REMEDIATION_HINT = "Run 'postgresai auth' to (re)authenticate, or set/update PGAI_API_KEY.";
-function formatHttpError(operation, status, responseBody) {
-  const statusMessage = HTTP_STATUS_MESSAGES[status] || "Request failed";
-  let errMsg = `${operation}: HTTP ${status} - ${statusMessage}`;
+var STANDARD_REASON_PHRASES = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  408: "Request Timeout",
+  409: "Conflict",
+  413: "Payload Too Large",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout"
+};
+function formatHttpError(operation, status, responseBody, statusText) {
+  const generic = HTTP_STATUS_MESSAGES[status] || "Request failed";
   const remediation = status === 401 ? `
 ${AUTH_REMEDIATION_HINT}` : "";
-  if (responseBody) {
-    if (isHtmlContent(responseBody)) {
-      return errMsg + remediation;
-    }
+  let bodyMessage;
+  let bodyDetails;
+  let bodyCode;
+  let bodyHint;
+  if (responseBody && !isHtmlContent(responseBody)) {
     try {
       const errObj = JSON.parse(responseBody);
-      const message = errObj.message || errObj.error || errObj.detail;
-      if (message && typeof message === "string") {
-        errMsg += `
-${message}`;
-      } else {
-        errMsg += `
-${JSON.stringify(errObj, null, 2)}`;
+      const message = errObj.message ?? errObj.error;
+      if (typeof message === "string" && message.trim().length > 0) {
+        bodyMessage = redactTextSecrets(message.trim());
+      }
+      const details = errObj.details ?? errObj.detail;
+      if (typeof details === "string" && details.trim().length > 0) {
+        bodyDetails = redactTextSecrets(details.trim());
+      }
+      if (typeof errObj.code === "string" && errObj.code.trim().length > 0) {
+        bodyCode = errObj.code.trim();
+      }
+      if (typeof errObj.hint === "string" && errObj.hint.trim().length > 0) {
+        bodyHint = redactTextSecrets(errObj.hint.trim());
+      }
+      if (bodyMessage === undefined && bodyDetails === undefined && bodyCode === undefined && bodyHint === undefined) {
+        bodyDetails = redactSecretsForLog(JSON.stringify(errObj));
       }
     } catch {
       const trimmed = responseBody.trim();
       if (trimmed.length > 0 && trimmed.length < 500) {
-        errMsg += `
-${trimmed}`;
+        bodyDetails = redactTextSecrets(trimmed);
       }
     }
   }
+  const trimmedReason = statusText?.trim();
+  const reasonPhrase = trimmedReason && trimmedReason !== STANDARD_REASON_PHRASES[status] && trimmedReason !== generic ? trimmedReason : undefined;
+  const safeReasonPhrase = reasonPhrase ? redactTextSecrets(reasonPhrase) : undefined;
+  const headline = bodyMessage ?? safeReasonPhrase ?? generic;
+  const codeSuffix = bodyCode && !headline.includes(bodyCode) ? ` (${bodyCode})` : "";
+  let errMsg = `${operation}: HTTP ${status} - ${headline}${codeSuffix}`;
+  if (bodyDetails && bodyDetails !== headline) {
+    errMsg += `
+${bodyDetails}`;
+  }
+  if (bodyHint) {
+    errMsg += `
+Hint: ${bodyHint}`;
+  }
   return errMsg + remediation;
 }
+function describeFetchError(operation, url, err) {
+  const cause = err?.cause;
+  const detail = cause?.code || cause?.message || (err instanceof Error && err.message ? err.message : String(err));
+  return `${operation}: could not reach ${url} (${detail})`;
+}
+
+class HttpStatusError extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "HttpStatusError";
+    this.status = status;
+  }
+}
+function isRetryableHttpStatus(status) {
+  return status >= 500 || status === 429;
+}
+var DEFAULT_HTTP_REQUEST_TIMEOUT_MS = 25000;
+
+class HttpRequestTimeoutError extends Error {
+  constructor(operation, timeoutMs) {
+    super(`${operation}: request timed out after ${timeoutMs}ms`);
+    this.name = "HttpRequestTimeoutError";
+  }
+}
+function requestTimeoutSignal(timeoutMs) {
+  const requested = typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_HTTP_REQUEST_TIMEOUT_MS;
+  const bounded = Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, Math.floor(requested)));
+  return { signal: AbortSignal.timeout(bounded), timeoutMs: bounded };
+}
+function isFetchTimeout(err) {
+  const name = err?.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
 function maskSecret(secret) {
   if (!secret)
     return "";
@@ -16436,6 +16596,37 @@ function maskSecret(secret) {
     return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
   return `${secret.slice(0, Math.min(12, secret.length - 8))}${"*".repeat(Math.max(4, secret.length - 16))}${secret.slice(-4)}`;
 }
+function isSensitiveLogKey(key) {
+  const normalized = key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+  return /^(?:password|passwd|db_(?:pass|password)|conn_?str|secret|token|api_key|private_key|access_key|access_token|refresh_token|auth|auth_key|auth_token|authorization|credentials?|dsn)$/.test(normalized);
+}
+function redactSecrets(value) {
+  if (Array.isArray(value)) {
+    return value.map(redactSecrets);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      out[key] = isSensitiveLogKey(key) && child != null ? "[REDACTED]" : redactSecrets(child);
+    }
+    return out;
+  }
+  return value;
+}
+function redactSecretsForLog(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return redactTextSecrets(text);
+  }
+  return JSON.stringify(redactSecrets(parsed));
+}
+var TEXT_URL_USERINFO = /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+):[^\s/@]+@/gi;
+var TEXT_SENSITIVE_PAIR = /((?:password|passwd|db[-_]?pass|connstr|secret|token|api[-_]?key|private[-_]?key|access[-_]?key|cred(?:ential)?s?|dsn)["']?\s*[:=]\s*)("[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+function redactTextSecrets(text) {
+  return text.replace(TEXT_URL_USERINFO, "$1:[REDACTED]@").replace(TEXT_SENSITIVE_PAIR, "$1[REDACTED]");
+}
 function normalizeBaseUrl(value) {
   const trimmed = (value || "").replace(/\/$/, "");
   try {
@@ -20973,7 +21164,7 @@ function finalize(ctx, schema2) {
     result.$schema = "http://json-schema.org/draft-07/schema#";
   } else if (ctx.target === "draft-04") {
     result.$schema = "http://json-schema.org/draft-04/schema#";
-  } else if (ctx.target === "openapi-3.0") {}
+  } else if (ctx.target === "openapi-3.0") {} else {}
   if (ctx.external?.uri) {
     const id = ctx.external.registry.get(schema2)?.id;
     if (!id)
@@ -21192,7 +21383,7 @@ var literalProcessor = (schema2, ctx, json2, _params) => {
     if (val === undefined) {
       if (ctx.unrepresentable === "throw") {
         throw new Error("Literal `undefined` cannot be represented in JSON Schema");
-      }
+      } else {}
     } else if (typeof val === "bigint") {
       if (ctx.unrepresentable === "throw") {
         throw new Error("BigInt literals cannot be represented in JSON Schema");
@@ -25801,6 +25992,352 @@ function renderMarkdownForTerminal(md) {
 `);
 }
 
+// lib/joe.ts
+var DEFAULT_BUDGET_MS = 25000;
+var DEFAULT_POLL_INTERVAL_MS = 800;
+async function callRpc(params) {
+  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/${fn}`);
+  const payload = JSON.stringify(body);
+  const headers = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${redactSecretsForLog(payload)}`);
+  }
+  let response;
+  const requestTimeout = requestTimeoutSignal(params.timeoutMs);
+  try {
+    response = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: payload,
+      signal: requestTimeout.signal
+    });
+  } catch (err) {
+    if (isFetchTimeout(err)) {
+      throw new HttpRequestTimeoutError(operation, requestTimeout.timeoutMs);
+    }
+    throw new Error(describeFetchError(operation, base, err));
+  }
+  const text = await response.text();
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${redactSecretsForLog(text)}`);
+  }
+  if (!response.ok) {
+    throw new HttpStatusError(formatHttpError(operation, response.status, text, response.statusText), response.status);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${redactSecretsForLog(text)}`);
+  }
+}
+async function startCommand(params) {
+  const { apiKey, apiBaseUrl, instanceId, command, debug, timeoutMs } = params;
+  if (!String(command ?? "").trim()) {
+    throw new Error("command text is required");
+  }
+  const commandId = await callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_run",
+    body: { instance_id: instanceId, command },
+    operation: "Failed to run Joe command",
+    debug,
+    timeoutMs
+  });
+  if (typeof commandId !== "string" || !/^[0-9]+$/.test(commandId)) {
+    throw new Error(`Failed to run Joe command: expected a command id string, got: ${redactSecretsForLog(JSON.stringify(commandId))}`);
+  }
+  return commandId;
+}
+async function getCommandOutput(params) {
+  const { apiKey, apiBaseUrl, commandId, debug, timeoutMs } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_output",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command output",
+    debug,
+    timeoutMs
+  });
+}
+function preserveIntegerId(value) {
+  if (typeof value === "number")
+    return value;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : value;
+}
+function normalizeProjectRow(row) {
+  return {
+    project_id: preserveIntegerId(row.project_id ?? 0),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    joe_ready: Boolean(row.joe_ready ?? false),
+    tunnel: Boolean(row.tunnel ?? false),
+    instance_id: row.instance_id == null ? null : preserveIntegerId(row.instance_id),
+    dblab_instance_id: row.dblab_instance_id == null ? null : preserveIntegerId(row.dblab_instance_id)
+  };
+}
+async function listProjects(params) {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
+  }
+  const rows = await callRpc({
+    apiKey,
+    apiBaseUrl,
+    fn: "projects_list",
+    body,
+    operation: "Failed to list projects",
+    debug
+  });
+  if (!Array.isArray(rows)) {
+    return [];
+  }
+  return rows.map(normalizeProjectRow);
+}
+function isNumericProjectRef(ref) {
+  return /^[0-9]+$/.test(ref.trim());
+}
+async function resolveJoeInstanceId(params) {
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  const projects = await listProjects({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug
+  });
+  const needle = ref.toLowerCase();
+  const match = isNumericProjectRef(ref) ? projects.find((p) => String(p.project_id) === String(preserveIntegerId(ref))) : projects.find((p) => p.alias !== null && p.alias.toLowerCase() === needle || p.name !== null && p.name.toLowerCase() === needle);
+  if (!match) {
+    throw new Error(`Project not found for id/alias/name '${ref}'. Run 'pgai projects' to see available projects.`);
+  }
+  if (match.instance_id == null) {
+    throw new Error(`Project '${ref}' has no Joe instance. Run 'pgai projects' to see which projects have Joe ready.`);
+  }
+  return match.instance_id;
+}
+var DESCRIBE_VARIANTS = [
+  "\\d",
+  "\\d+",
+  "\\dt",
+  "\\dt+",
+  "\\di",
+  "\\di+",
+  "\\l",
+  "\\l+",
+  "\\dv",
+  "\\dv+",
+  "\\dm",
+  "\\dm+"
+];
+function buildJoeCommandText(command, input = {}) {
+  const arg = String(input.arg ?? "").trim();
+  switch (command) {
+    case "plan":
+    case "explain":
+    case "exec":
+    case "hypo": {
+      if (!arg) {
+        throw new Error(`${command} requires an argument`);
+      }
+      return `${command} ${arg}`;
+    }
+    case "activity":
+    case "reset":
+      return command;
+    case "terminate": {
+      if (!/^[1-9][0-9]*$/.test(arg)) {
+        throw new Error("pid must be a positive integer");
+      }
+      return `terminate ${arg}`;
+    }
+    case "describe": {
+      if (!arg) {
+        throw new Error("describe requires an object name");
+      }
+      const variant = String(input.variant ?? "\\d").trim();
+      if (!DESCRIBE_VARIANTS.includes(variant)) {
+        throw new Error(`Unsupported describe variant '${variant}'. Supported: ${DESCRIBE_VARIANTS.join(" ")}`);
+      }
+      return `${variant} ${arg}`;
+    }
+  }
+}
+var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function runCommand(params) {
+  const { apiKey, apiBaseUrl, instanceId, command, debug } = params;
+  const budgetMs = typeof params.budgetMs === "number" && Number.isFinite(params.budgetMs) && params.budgetMs >= 0 ? params.budgetMs : DEFAULT_BUDGET_MS;
+  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const now = params.now ?? Date.now;
+  const sleep = params.sleep ?? defaultSleep;
+  const commandId = await startCommand({ apiKey, apiBaseUrl, instanceId, command, debug });
+  const deadline = now() + budgetMs;
+  let status = "pending";
+  const remainingRequestMs = () => Math.max(1, Math.min(DEFAULT_HTTP_REQUEST_TIMEOUT_MS, deadline - now()));
+  if (now() >= deadline) {
+    return { commandId, status, output: null, budgetExpired: true };
+  }
+  for (;; ) {
+    let output;
+    try {
+      output = await getCommandOutput({
+        apiKey,
+        apiBaseUrl,
+        commandId,
+        debug,
+        timeoutMs: remainingRequestMs()
+      });
+    } catch (err) {
+      if (err instanceof HttpRequestTimeoutError) {
+        return { commandId, status, output: null, budgetExpired: true };
+      }
+      if (err instanceof HttpStatusError && isRetryableHttpStatus(err.status)) {
+        if (now() >= deadline) {
+          return { commandId, status, output: null, budgetExpired: true };
+        }
+        await sleep(pollIntervalMs);
+        continue;
+      }
+      throw err;
+    }
+    status = output.status;
+    if (status === "ok" || status === "error") {
+      return { commandId, status, output, budgetExpired: false };
+    }
+    if (now() >= deadline) {
+      return { commandId, status, output: null, budgetExpired: true };
+    }
+    await sleep(pollIntervalMs);
+  }
+}
+async function executeJoeCommand(params) {
+  const commandText = buildJoeCommandText(params.command, params.input);
+  let instanceId;
+  const directRef = String(params.instanceId ?? "").trim();
+  if (directRef) {
+    if (!/^[0-9]+$/.test(directRef)) {
+      throw new Error("instanceId must be a numeric Joe instance id");
+    }
+    instanceId = directRef;
+  } else if (String(params.project ?? "").trim()) {
+    instanceId = await resolveJoeInstanceId({
+      apiKey: params.apiKey,
+      apiBaseUrl: params.apiBaseUrl,
+      project: String(params.project),
+      orgId: params.orgId,
+      debug: params.debug
+    });
+  } else {
+    throw new Error("either instanceId or project is required");
+  }
+  const outcome = await runCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    instanceId,
+    command: commandText,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep
+  });
+  return { ...outcome, command: params.command, instanceId, commandText };
+}
+function clientSidePlanFlags(planJson) {
+  const flags = [];
+  const walk = (node) => {
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    const nodeType = node["Node Type"];
+    if (nodeType === "Seq Scan") {
+      const rel = node["Relation Name"];
+      flags.push(`client-side: Seq Scan${rel ? ` on ${rel}` : ""} — no index serves this predicate; consider adding one.`);
+    }
+    if (Array.isArray(node.Plans)) {
+      for (const child of node.Plans) {
+        walk(child);
+      }
+    }
+  };
+  if (Array.isArray(planJson)) {
+    for (const entry of planJson) {
+      if (entry && typeof entry === "object") {
+        walk(entry.Plan ?? entry);
+      }
+    }
+    return flags;
+  }
+  if (planJson && typeof planJson === "object") {
+    const root = planJson;
+    walk(root.Plan ?? planJson);
+  }
+  return flags;
+}
+function formatJoeOutput(output) {
+  const lines = [];
+  const section = (value, label) => {
+    if (value == null || value.trim() === "")
+      return;
+    if (lines.length > 0)
+      lines.push("");
+    if (label)
+      lines.push(`${label}:`);
+    lines.push(value);
+  };
+  section(output.response);
+  section(output.plan_text, "plan");
+  const flags = clientSidePlanFlags(output.plan_json).map((flag) => `⚑ ${flag}`);
+  if (flags.length > 0) {
+    lines.push(...flags);
+  }
+  section(output.plan_execution_text, "execution plan (EXPLAIN ANALYZE)");
+  section(output.stats, "stats");
+  section(output.recommendations, "recommendations");
+  if (output.queryid) {
+    if (lines.length > 0)
+      lines.push("");
+    lines.push(`(queryid ${output.queryid})`);
+  }
+  return lines.join(`
+`);
+}
+function formatProjectsTable(projects) {
+  const header = ["PROJECT_ID", "ALIAS", "PROJECT", "JOE", "TUNNEL"];
+  const rows = projects.map((p) => [
+    String(p.project_id),
+    p.alias ?? "-",
+    p.name ?? "-",
+    p.joe_ready ? "ready" : "no",
+    p.tunnel ? "yes" : "no"
+  ]);
+  const widths = header.map((h, i2) => Math.max(h.length, ...rows.map((r) => r[i2].length), 0));
+  const pad = (cells) => cells.map((c, i2) => c.padEnd(i2 === cells.length - 1 ? 0 : widths[i2])).join("  ").trimEnd();
+  return [pad(header), ...rows.map(pad)].join(`
+`);
+}
+
 // bin/postgres-ai.ts
 init_util();
 
@@ -29452,10 +29989,6 @@ async function verifyInitSetup(params) {
         }
       }
     }
-    const explainFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok", [role]);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
     const tableDescribeFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.table_describe(text)', 'EXECUTE') as ok", [role]);
     if (!tableDescribeFnRes.rows?.[0]?.ok) {
       missingRequired.push("EXECUTE on postgres_ai.table_describe(text)");
@@ -29522,10 +30055,28 @@ async function checkCurrentUserPermissions(client) {
 
       union all
 
+      select
+        'postgres_ai schema exists' as permission_name,
+        'optional' as status,
+        to_regnamespace('postgres_ai') is not null as granted
+
+      union all
+
+      select
+        'usage on postgres_ai schema' as permission_name,
+        'optional' as status,
+        case
+          when to_regnamespace('postgres_ai') is null then null
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as granted
+
+      union all
+
       select
         'postgres_ai.pg_statistic view exists' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           else to_regclass('postgres_ai.pg_statistic') is not null
         end as granted
@@ -29536,6 +30087,7 @@ async function checkCurrentUserPermissions(client) {
         'select on postgres_ai.pg_statistic' as permission_name,
         'optional' as status,
         case
+          when to_regnamespace('postgres_ai') is null then null
           when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then null
           when to_regclass('postgres_ai.pg_statistic') is null then null
           else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'select')
@@ -29555,6 +30107,10 @@ async function checkCurrentUserPermissions(client) {
             when permission_name like 'select on pg_catalog.pg_index' then
               format('grant select on pg_catalog.pg_index to %I;', current_user)
           end
+        when permission_name = 'postgres_ai schema exists' and granted = false then
+          '-- run postgresai prepare-db or create the postgres_ai schema and pg_statistic view manually'
+        when permission_name = 'usage on postgres_ai schema' and granted = false then
+          format('grant usage on schema postgres_ai to %I;', current_user)
         when permission_name = 'postgres_ai.pg_statistic view exists' and granted = false then
           '-- create postgres_ai.pg_statistic view (see setup script)'
         when permission_name = 'select on postgres_ai.pg_statistic' and granted = false then
@@ -29581,6 +30137,10 @@ function formatPermissionCheckMessages(result) {
   const warnings = [];
   const errors3 = [];
   for (const row of result.missingOptional) {
+    if (row.permission_name === "postgres_ai schema exists") {
+      warnings.push("Warning: optional: postgres_ai schema not found — F004/F005 (bloat estimates) will be skipped; run prepare-db or create the view manually to enable them.");
+      continue;
+    }
     const fix = row.fix_command ? ` Fix: ${row.fix_command}` : "";
     warnings.push(`Warning: optional permission missing — ${row.permission_name}.${fix}`);
   }
@@ -29974,15 +30534,6 @@ async function verifyInitSetupViaSupabase(params) {
       missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
     }
   }
-  const explainFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'explain_generic' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
-  if (explainFnExistsRes.rowCount === 0) {
-    missingRequired.push("function postgres_ai.explain_generic exists");
-  } else {
-    const explainFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok`, true);
-    if (!explainFnRes.rows?.[0]?.ok) {
-      missingRequired.push("EXECUTE on postgres_ai.explain_generic(text, text, text)");
-    }
-  }
   const tableDescribeFnExistsRes = await params.client.query("SELECT oid FROM pg_proc WHERE proname = 'table_describe' AND pronamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'postgres_ai')", true);
   if (tableDescribeFnExistsRes.rowCount === 0) {
     missingRequired.push("function postgres_ai.table_describe exists");
@@ -32013,7 +32564,7 @@ function buildCheckInfoMap() {
 }
 
 // lib/checkup.ts
-var __dirname = "/builds/postgres-ai/postgresai/cli/lib";
+var __dirname = "/Users/nik/gitlab/postgresai-wt-joe-cli/cli/lib";
 var SECONDS_PER_DAY = 86400;
 var SECONDS_PER_HOUR = 3600;
 var SECONDS_PER_MINUTE = 60;
@@ -32778,12 +33329,70 @@ async function generateF003(client, nodeName) {
   };
   return report;
 }
+function bloatErrorStatus(err) {
+  const error2 = err instanceof Error ? err.message : String(err);
+  const code = typeof err === "object" && err !== null && "code" in err ? String(err.code || "") : "";
+  const normalized = error2.toLowerCase();
+  let reason = "query_error";
+  if (code === "3F000" || normalized.includes('schema "postgres_ai" does not exist')) {
+    reason = "missing_schema";
+  } else if (code === "42P01" || normalized.includes('relation "postgres_ai.pg_statistic" does not exist')) {
+    reason = "missing_view";
+  } else if (code === "42501" || normalized.includes("permission denied")) {
+    reason = "missing_grant";
+  }
+  return { ok: false, reason, error: error2 };
+}
+async function getBloatCheckStatus(client) {
+  try {
+    const result = await client.query(`
+      select
+        to_regnamespace('postgres_ai') is not null as schema_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          else has_schema_privilege(current_user, 'postgres_ai', 'USAGE')
+        end as schema_usage,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          else to_regclass('postgres_ai.pg_statistic') is not null
+        end as view_exists,
+        case
+          when to_regnamespace('postgres_ai') is null then false
+          when not has_schema_privilege(current_user, 'postgres_ai', 'USAGE') then false
+          when to_regclass('postgres_ai.pg_statistic') is null then false
+          else has_table_privilege(current_user, 'postgres_ai.pg_statistic', 'SELECT')
+        end as view_select
+    `);
+    const capability = result.rows[0] || {};
+    if (!capability.schema_exists) {
+      return { ok: false, reason: "missing_schema", error: 'schema "postgres_ai" does not exist' };
+    }
+    if (!capability.schema_usage) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for schema postgres_ai" };
+    }
+    if (!capability.view_exists) {
+      return { ok: false, reason: "missing_view", error: 'relation "postgres_ai.pg_statistic" does not exist' };
+    }
+    if (!capability.view_select) {
+      return { ok: false, reason: "missing_grant", error: "permission denied for relation postgres_ai.pg_statistic" };
+    }
+    return { ok: true, reason: null, error: null };
+  } catch (err) {
+    return bloatErrorStatus(err);
+  }
+}
 async function generateF004(client, nodeName) {
   const report = createBaseReport("F004", "Autovacuum: heap bloat (estimated)", nodeName);
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedTables = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F004, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32827,7 +33436,8 @@ async function generateF004(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F004] Error estimating table bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32837,6 +33447,7 @@ async function generateF004(client, nodeName) {
   const totalCount = bloatedTables.length;
   const totalBloatSizeBytes = bloatedTables.reduce((sum, t) => sum + t.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_tables: bloatedTables,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -32855,7 +33466,12 @@ async function generateF005(client, nodeName) {
   const postgresVersion = await getPostgresVersion(client);
   const pgMajorVersion = parseInt(postgresVersion.server_major_ver, 10);
   let bloatedIndexes = [];
+  let status = await getBloatCheckStatus(client);
   try {
+    if (!status.ok)
+      throw Object.assign(new Error(status.error || "Bloat prerequisites unavailable"), {
+        code: status.reason === "missing_schema" ? "3F000" : status.reason === "missing_view" ? "42P01" : status.reason === "missing_grant" ? "42501" : undefined
+      });
     const sql = getMetricSql(METRIC_NAMES.F005, pgMajorVersion);
     const bloatResult = await client.query(sql);
     const vacuumStatsResult = await client.query(`
@@ -32904,7 +33520,8 @@ async function generateF005(client, nodeName) {
       };
     });
   } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err);
+    status = bloatErrorStatus(err);
+    const errorMsg = status.error || "Unknown error";
     console.error(`[F005] Error estimating index bloat: ${errorMsg}`);
     if (errorMsg.includes("postgres_ai.")) {
       console.error(`  Hint: Run "postgresai prepare-db <connection>" to create required objects.`);
@@ -32914,6 +33531,7 @@ async function generateF005(client, nodeName) {
   const totalCount = bloatedIndexes.length;
   const totalBloatSizeBytes = bloatedIndexes.reduce((sum, idx) => sum + idx.bloat_size, 0);
   const dbEntry = {
+    status,
     bloated_indexes: bloatedIndexes,
     total_count: totalCount,
     total_bloat_size_bytes: totalBloatSizeBytes,
@@ -33586,6 +34204,10 @@ function generateCheckSummary(checkId, report) {
       return summarizeF001(nodeData);
     case "F003":
       return summarizeF003(nodeData);
+    case "F004":
+      return summarizeBloat(nodeData, "table");
+    case "F005":
+      return summarizeBloat(nodeData, "index");
     case "G001":
       return summarizeG001(nodeData);
     case "G003":
@@ -33771,6 +34393,25 @@ function summarizeF003(nodeData) {
   }
   return { status: "warning", message: parts.join(", ") };
 }
+function summarizeBloat(nodeData, kind) {
+  const data = nodeData?.data || {};
+  let totalCount = 0;
+  for (const dbData of Object.values(data)) {
+    const dbEntry = dbData;
+    if (dbEntry?.status?.ok === false) {
+      const reason = String(dbEntry.status.reason || "query_error").replaceAll("_", " ");
+      return { status: "warning", message: `Bloat estimate degraded: ${reason}` };
+    }
+    totalCount += dbEntry?.total_count || 0;
+  }
+  if (totalCount === 0) {
+    return { status: "ok", message: `No bloated ${kind}${kind === "index" ? "es" : "s"} found` };
+  }
+  return {
+    status: "warning",
+    message: `Found ${totalCount} bloated ${kind}${totalCount === 1 ? "" : kind === "index" ? "es" : "s"}`
+  };
+}
 function summarizeG001(nodeData) {
   const data = nodeData?.data || {};
   const settingsCount = Object.keys(data).length;
@@ -34127,9 +34768,15 @@ function prepareUploadConfig(opts, rootOpts, shouldUpload, uploadExplicitlyReque
       console.error("Tip: run 'postgresai auth' or pass --api-key / set PGAI_API_KEY");
       return null;
     }
-    console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
-    console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
-    console.error("        To run locally without this notice, pass --no-upload.");
+    if (opts.markdown) {
+      console.error("Notice: no API key configured \u2014 regular report upload is disabled.");
+      console.error("        The full report JSON will still be sent to the PostgresAI API for markdown conversion.");
+      console.error("        To avoid sending report data, replace --markdown with --no-upload and --json or --output.");
+    } else {
+      console.error("Notice: no API key configured \u2014 results will NOT be uploaded to PostgresAI.");
+      console.error("        To upload: run 'postgresai auth login' or pass --api-key / set PGAI_API_KEY.");
+      console.error("        To run locally without this notice, pass --no-upload.");
+    }
     return;
   }
   const cfg = readConfig();
@@ -35354,7 +36001,7 @@ program2.command("unprepare-db [conn]").description("remove monitoring setup: dr
     closeReadline();
   }
 });
-program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown to stdout").addHelpText("after", [
+program2.command("checkup [checkIdOrConn] [conn]").description("generate health check reports directly from PostgreSQL (express mode)").option("--check-id <id>", `specific check to run (see list below), or ALL`).option("--node-name <name>", "node name for reports", "node-01").option("--output <path>", "output directory for JSON files").option("--upload", "upload JSON results to PostgresAI (requires API key)").option("--no-upload", "disable upload to PostgresAI").option("--project <project>", "project name or ID for remote upload (used with --upload; defaults to config defaultProject; auto-generated on first run)").option("--json", "output JSON to stdout").option("--markdown", "output markdown via PostgresAI API (transmits the full report JSON)").addHelpText("after", [
   "",
   "Available checks:",
   ...Object.entries(CHECK_INFO).map(([id, title]) => `  ${id}: ${title}`),
@@ -35365,7 +36012,7 @@ program2.command("checkup [checkIdOrConn] [conn]").description("generate health
   "  postgresai checkup postgresql://user:pass@host:5432/db --check-id H002",
   "  postgresai checkup postgresql://user:pass@host:5432/db --output ./reports",
   "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --json",
-  "  postgresai checkup postgresql://user:pass@host:5432/db --no-upload --markdown"
+  "  postgresai checkup postgresql://user:pass@host:5432/db --markdown"
 ].join(`
 `)).action(async (checkIdOrConn, connArg, opts, cmd) => {
   const checkIdPattern = /^[A-Z]\d{3}$/i;
@@ -35405,6 +36052,13 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
     return;
   }
   const uploadExplicitlyDisabled = opts.upload === false;
+  if (uploadExplicitlyDisabled && shouldConvertMarkdown) {
+    console.error("Error: --no-upload and --markdown are mutually exclusive");
+    console.error("Markdown conversion is performed by the PostgresAI API and transmits the full report JSON.");
+    console.error("Drop --no-upload to allow transmission, or use --json or --output for local-only output.");
+    process.exitCode = 1;
+    return;
+  }
   let shouldUpload = !uploadExplicitlyDisabled;
   const outputPath = prepareOutputDirectory(opts.output);
   if (outputPath === null) {
@@ -35587,7 +36241,9 @@ Usage: postgresai checkup ${checkId} postgresql://user@host:5432/dbname
       console.log(`
 For details:`);
       console.log("  --json          Output JSON");
-      console.log("  --markdown      Output markdown");
+      if (!uploadExplicitlyDisabled) {
+        console.log("  --markdown      Output markdown via PostgresAI API");
+      }
       console.log("  --output <dir>  Save to directory");
     }
   } catch (error2) {
@@ -35659,6 +36315,16 @@ function checkRunningContainers() {
     return { running: false, containers: [] };
   }
 }
+function planMonitoringRegistration(args) {
+  const projectName = args.project?.trim() || undefined;
+  if (args.instanceId) {
+    return { kind: "adopt", projectName };
+  }
+  if (!projectName) {
+    return { kind: "error-missing-project", projectName: undefined };
+  }
+  return { kind: "self-register", projectName };
+}
 async function registerMonitoringInstance(apiKey, projectName, opts) {
   const { apiBaseUrl } = resolveBaseUrls2(opts);
   const url = `${apiBaseUrl}/rpc/monitoring_instance_register`;
@@ -35666,16 +36332,19 @@ async function registerMonitoringInstance(apiKey, projectName, opts) {
   const instanceId = opts?.instanceId;
   const retries = opts?.retries ?? (instanceId ? 1 : 0);
   const retryDelayMs = opts?.retryDelayMs ?? 400;
+  const hasProjectName = !!(projectName && projectName.trim());
   if (debug) {
     console.error(`
 Debug: Registering monitoring instance...`);
     console.error(`Debug: POST ${url}`);
-    console.error(`Debug: project_name=${projectName}${instanceId ? ` instance_id=${instanceId}` : ""}`);
+    console.error(`Debug: ${hasProjectName ? `project_name=${projectName}` : "project_name=(omitted)"}${instanceId ? ` instance_id=${instanceId}` : ""}`);
   }
   const requestBody = {
-    api_token: apiKey,
-    project_name: projectName
+    api_token: apiKey
   };
+  if (hasProjectName) {
+    requestBody.project_name = projectName;
+  }
   if (instanceId) {
     requestBody.instance_id = instanceId;
   }
@@ -36218,8 +36887,9 @@ Searched: ${demoCandidates.join(", ")}
   console.log(`\u2713 Services started
 `);
   if (apiKey && !opts.demo) {
-    const projectName = opts.project || "postgres-ai-monitoring";
     const instanceId = opts.instanceId || process.env.PGAI_INSTANCE_ID;
+    const plan = planMonitoringRegistration({ project: opts.project, instanceId });
+    const projectName = plan.projectName;
     if (instanceId) {
       const reg = await registerMonitoringInstance(apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -36235,9 +36905,9 @@ Searched: ${demoCandidates.join(", ")}
         console.log(`\u2713 ${verb} monitoring instance (project: ${adoptedProject})
 `);
       } else if (reg) {
-        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project \u2014 reports will use project '${projectName}'`);
+        console.error(`\u26A0 Adopted provisioned instance ${instanceId} but the platform returned no project` + (projectName ? ` \u2014 reports will use project '${projectName}'` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
       } else {
-        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId} \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run`);
+        console.error(`\u26A0 Could not adopt provisioned instance ${instanceId}` + (projectName ? ` \u2014 reports will use project '${projectName}' until 'postgresai mon local-install' is re-run` : ` \u2014 reports will have no project until 'postgresai mon local-install' is re-run with --project <name>`));
       }
       const aas = await registerAasCollection(apiKey, instanceId, {
         grafanaPassword,
@@ -36253,6 +36923,9 @@ Searched: ${demoCandidates.join(", ")}
         console.error(`\u26A0 AAS auto-collection not registered (${aas.reason}); it can be enabled later by re-running 'postgresai mon local-install'
 `);
       }
+    } else if (plan.kind === "error-missing-project") {
+      console.error("\u2717 A project name is required for self-registration (the 'postgres-ai-monitoring' default was removed). " + "Re-run with --project <name>, or adopt a console-provisioned instance with --instance-id <uuid>.");
+      process.exitCode = 1;
     } else {
       registerMonitoringInstance(apiKey, projectName, {
         apiBaseUrl: globalOpts.apiBaseUrl,
@@ -36785,7 +37458,7 @@ targets.command("test <name>").description("test monitoring target database conn
   }
 });
 var auth = program2.command("auth").description("authentication and API key management");
-auth.command("login", { isDefault: true }).description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output").action(async (opts) => {
+async function runAuthLogin(opts) {
   if (opts.setKey) {
     const trimmedKey = opts.setKey.trim();
     if (!trimmedKey) {
@@ -36986,7 +37659,12 @@ Authentication failed: ${message}`);
     console.error(`Authentication error: ${message}`);
     process.exit(1);
   }
-});
+}
+function configureLoginCommand(command) {
+  return command.description("authenticate via browser (OAuth) or store API key directly").option("--set-key <key>", "store API key directly without OAuth flow").option("--port <port>", "local callback server port (default: random)", parseInt).option("--debug", "enable debug output");
+}
+configureLoginCommand(auth.command("login", { isDefault: true })).action(runAuthLogin);
+configureLoginCommand(program2.command("login")).action(runAuthLogin);
 auth.command("show-key").description("show API key (masked)").action(async () => {
   const cfg = readConfig();
   if (!cfg.apiKey) {
@@ -37889,6 +38567,177 @@ function tryParseJson(s) {
     return s;
   }
 }
+function printJoeOutcome(outcome, json3, budgetMs) {
+  const effectiveBudgetMs = typeof budgetMs === "number" && Number.isFinite(budgetMs) ? budgetMs : DEFAULT_BUDGET_MS;
+  const budgetSeconds = Math.round(effectiveBudgetMs / 1000);
+  if (outcome.budgetExpired) {
+    if (json3) {
+      console.log(JSON.stringify({
+        command_id: outcome.commandId,
+        status: outcome.status,
+        budget_expired: true,
+        resume: `pgai joe result ${outcome.commandId}`
+      }, null, 2));
+    } else {
+      console.log(`started ${outcome.commandId} \xB7 ${outcome.status} \xB7 budget ${budgetSeconds}s reached \u2014 resume:  pgai joe result ${outcome.commandId}`);
+    }
+    return;
+  }
+  const output = outcome.output;
+  if (outcome.status === "ok") {
+    if (!output) {
+      console.error(`command ${outcome.commandId} ok but output is empty`);
+      process.exitCode = 1;
+      return;
+    }
+    if (json3)
+      console.log(JSON.stringify(output, null, 2));
+    else {
+      console.log(`command ${outcome.commandId} \xB7 ok`);
+      const body = formatJoeOutput(output);
+      if (body)
+        console.log(body);
+    }
+    return;
+  }
+  if (json3 && output)
+    console.log(JSON.stringify(output, null, 2));
+  console.error(`command ${outcome.commandId} error: ${output?.error ?? "command failed"}`);
+  process.exitCode = 1;
+}
+async function runJoeCli(command, arg, opts) {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const projectRef = (opts.project ?? cfg.defaultProject ?? "").toString().trim();
+    const instanceRef = (opts.instanceId ?? "").toString().trim();
+    if (!projectRef && !instanceRef) {
+      console.error("Specify --instance-id <id> (or --project <id|alias> once projects_list is available).");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    if (typeof opts.budget === "number" && (!Number.isFinite(opts.budget) || opts.budget < 0)) {
+      throw new Error("--budget must be a non-negative number of seconds");
+    }
+    const budgetMs = typeof opts.budget === "number" ? opts.budget * 1000 : undefined;
+    const outcome = await executeJoeCommand({
+      apiKey,
+      apiBaseUrl,
+      command,
+      project: projectRef || undefined,
+      instanceId: instanceRef || undefined,
+      input: { arg, variant: opts.variant ?? null },
+      orgId: cfg.orgId ?? undefined,
+      budgetMs,
+      debug: !!opts.debug
+    });
+    printJoeOutcome(outcome, !!opts.json, budgetMs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+}
+function withJoeOptions(cmd) {
+  return cmd.option("--instance-id <id>", "target the Joe instance id directly (skips --project resolution; the v1 path while projects_list is unavailable)").option("--project <id|alias>", "target project by numeric id OR alias/name (requires projects_list)").option("--budget <seconds>", "one-shot poll budget in seconds (default 25)", (v) => parseFloat(v)).option("--debug", "enable debug output").option("--json", "output raw JSON");
+}
+var joe = program2.command("joe").description("Joe \u2014 plan/EXPLAIN/exec queries on ephemeral DBLab clones");
+withJoeOptions(joe.command("plan <sql>").description("plan a query (EXPLAIN, plan-only \u2014 no execution; the fast/safe default)")).action(async (sql, opts) => {
+  await runJoeCli("plan", sql, opts);
+});
+withJoeOptions(joe.command("explain <sql>").description("EXPLAIN + EXPLAIN ANALYZE a query (EXECUTES on the ephemeral clone)")).action(async (sql, opts) => {
+  await runJoeCli("explain", sql, opts);
+});
+withJoeOptions(joe.command("exec <sql>").description("run arbitrary DDL/DML on the clone (e.g. create index, analyze)")).action(async (sql, opts) => {
+  await runJoeCli("exec", sql, opts);
+});
+withJoeOptions(joe.command("hypo <args>").description("HypoPG hypothetical indexes (e.g. `hypo create index on users (email)`, `hypo desc`, `hypo reset`)")).action(async (args, opts) => {
+  await runJoeCli("hypo", args, opts);
+});
+withJoeOptions(joe.command("activity").description("running-activity snapshot (pg_stat_activity) on the clone")).action(async (opts) => {
+  await runJoeCli("activity", null, opts);
+});
+withJoeOptions(joe.command("terminate <pid>").description("pg_terminate_backend(pid) on the clone")).action(async (pid, opts) => {
+  await runJoeCli("terminate", pid, opts);
+});
+withJoeOptions(joe.command("reset").description("reset/recreate the session's thin clone")).action(async (opts) => {
+  await runJoeCli("reset", null, opts);
+});
+withJoeOptions(joe.command("describe <object>").description("\\d-family schema/relation/index metadata").option("--variant <variant>", "\\d-family variant (e.g. \\d+, \\di, \\dt)")).action(async (object4, opts) => {
+  await runJoeCli("describe", object4, opts);
+});
+joe.command("result <commandId>").description("fetch a Joe command's output by id (resume a budget-expired one-shot)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commandId, opts) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const output = await getCommandOutput({ apiKey, apiBaseUrl, commandId, debug: !!opts.debug });
+    if (opts.json) {
+      console.log(JSON.stringify(output, null, 2));
+      if (output.status !== "ok") {
+        process.exitCode = 1;
+      }
+      return;
+    }
+    if (output.status === "ok") {
+      console.log(`command ${output.command_id} \xB7 ok`);
+      const body = formatJoeOutput(output);
+      if (body)
+        console.log(body);
+    } else if (output.status === "error") {
+      console.error(`command ${output.command_id} error: ${output.error ?? "command failed"}`);
+      process.exitCode = 1;
+    } else {
+      console.error(`command ${output.command_id} \xB7 ${output.status} \u2014 result is not ready`);
+      process.exitCode = 1;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+program2.command("projects").description("list the org's projects (shows which have Joe ready) \u2014 org-level, not a Joe endpoint").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
+    }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const projects = await listProjects({
+      apiKey,
+      apiBaseUrl,
+      orgId: cfg.orgId ?? undefined,
+      debug: !!opts.debug
+    });
+    if (opts.json) {
+      console.log(JSON.stringify(projects, null, 2));
+    } else {
+      console.log(formatProjectsTable(projects));
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
 var mcp = program2.command("mcp").description("MCP server integration");
 mcp.command("start").description("start MCP stdio server").option("--debug", "enable debug output").action(async (opts) => {
   const rootOpts = program2.opts();
@@ -38018,5 +38867,6 @@ export {
   registerMonitoringInstance,
   refreshBundledComposeIfStale,
   readDeployedTag,
+  planMonitoringRegistration,
   isValidComposeYaml
 };