postgresai 0.14.0-beta.12 → 0.14.0-beta.13

package/dist/bin/postgres-ai.js

@@ -13064,7 +13064,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.14.0-beta.12",
+  version: "0.14.0-beta.13",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -15887,7 +15887,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.14.0-beta.12";
+var version = "0.14.0-beta.13";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -16079,13 +16079,24 @@ function resolveBaseUrls(opts, cfg, defaults2 = {}) {
 
 // lib/issues.ts
 async function fetchIssues(params) {
-  const { apiKey, apiBaseUrl, debug } = params;
+  const { apiKey, apiBaseUrl, orgId, status, limit = 20, offset = 0, debug } = params;
   if (!apiKey) {
     throw new Error("API key is required");
   }
   const base = normalizeBaseUrl(apiBaseUrl);
   const url = new URL(`${base}/issues`);
   url.searchParams.set("select", "id,title,status,created_at");
+  url.searchParams.set("order", "id.desc");
+  url.searchParams.set("limit", String(limit));
+  url.searchParams.set("offset", String(offset));
+  if (typeof orgId === "number") {
+    url.searchParams.set("org_id", `eq.${orgId}`);
+  }
+  if (status === "open") {
+    url.searchParams.set("status", "eq.0");
+  } else if (status === "closed") {
+    url.searchParams.set("status", "eq.1");
+  }
   const headers = {
     "access-token": apiKey,
     Prefer: "return=representation",
@@ -16170,7 +16181,7 @@ async function fetchIssue(params) {
   }
   const base = normalizeBaseUrl(apiBaseUrl);
   const url = new URL(`${base}/issues`);
-  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name");
+  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name,action_items");
   url.searchParams.set("id", `eq.${issueId}`);
   url.searchParams.set("limit", "1");
   const headers = {
@@ -16198,11 +16209,20 @@ async function fetchIssue(params) {
   if (response.ok) {
     try {
       const parsed = JSON.parse(data);
-      if (Array.isArray(parsed)) {
-        return parsed[0] ?? null;
-      } else {
-        return parsed;
+      const rawIssue = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (!rawIssue) {
+        return null;
       }
+      const actionItemsSummary = Array.isArray(rawIssue.action_items) ? rawIssue.action_items.map((item) => ({ id: item.id, title: item.title })) : [];
+      return {
+        id: rawIssue.id,
+        title: rawIssue.title,
+        description: rawIssue.description,
+        status: rawIssue.status,
+        created_at: rawIssue.created_at,
+        author_display_name: rawIssue.author_display_name,
+        action_items: actionItemsSummary
+      };
     } catch {
       throw new Error(`Failed to parse issue response: ${data}`);
     }
@@ -16441,6 +16461,243 @@ async function updateIssueComment(params) {
     throw new Error(formatHttpError("Failed to update issue comment", response.status, data));
   }
 }
+async function fetchActionItem(params) {
+  const { apiKey, apiBaseUrl, actionItemIds, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  const rawIds = Array.isArray(actionItemIds) ? actionItemIds : [actionItemIds];
+  const validIds = rawIds.filter((id) => id != null && typeof id === "string").map((id) => id.trim()).filter((id) => id.length > 0 && uuidPattern.test(id));
+  if (validIds.length === 0) {
+    throw new Error("actionItemId is required and must be a valid UUID");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  if (validIds.length === 1) {
+    url.searchParams.set("id", `eq.${validIds[0]}`);
+  } else {
+    url.searchParams.set("id", `in.(${validIds.join(",")})`);
+  }
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      const parsed = JSON.parse(data);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+      return parsed ? [parsed] : [];
+    } catch {
+      throw new Error(`Failed to parse action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action item", response.status, data));
+  }
+}
+async function fetchActionItems(params) {
+  const { apiKey, apiBaseUrl, issueId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  url.searchParams.set("issue_id", `eq.${issueId.trim()}`);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(`Failed to parse action items response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action items", response.status, data));
+  }
+}
+async function createActionItem(params) {
+  const { apiKey, apiBaseUrl, issueId, title, description, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+  if (!title) {
+    throw new Error("title is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_create`);
+  const bodyObj = {
+    issue_id: issueId,
+    title
+  };
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(`Failed to parse create action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to create action item", response.status, data));
+  }
+}
+async function updateActionItem(params) {
+  const { apiKey, apiBaseUrl, actionItemId, title, description, isDone, status, statusReason, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!actionItemId) {
+    throw new Error("actionItemId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(actionItemId.trim())) {
+    throw new Error("actionItemId must be a valid UUID");
+  }
+  const hasUpdateField = title !== undefined || description !== undefined || isDone !== undefined || status !== undefined || statusReason !== undefined || sqlAction !== undefined || configs !== undefined;
+  if (!hasUpdateField) {
+    throw new Error("At least one field to update is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_update`);
+  const bodyObj = {
+    action_item_id: actionItemId
+  };
+  if (title !== undefined) {
+    bodyObj.title = title;
+  }
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (isDone !== undefined) {
+    bodyObj.is_done = isDone;
+  }
+  if (status !== undefined) {
+    bodyObj.status = status;
+  }
+  if (statusReason !== undefined) {
+    bodyObj.status_reason = statusReason;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  if (!response.ok) {
+    const data = await response.text();
+    throw new Error(formatHttpError("Failed to update action item", response.status, data));
+  }
+}
 
 // node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
@@ -23350,7 +23607,16 @@ async function handleToolCall(req, rootOpts, extra) {
   }
   try {
     if (toolName === "list_issues") {
-      const issues = await fetchIssues({ apiKey, apiBaseUrl, debug });
+      const orgId = args.org_id !== undefined ? Number(args.org_id) : cfg.orgId ?? undefined;
+      const statusArg = args.status ? String(args.status) : undefined;
+      let status;
+      if (statusArg === "open")
+        status = "open";
+      else if (statusArg === "closed")
+        status = "closed";
+      const limit = args.limit !== undefined ? Number(args.limit) : undefined;
+      const offset = args.offset !== undefined ? Number(args.offset) : undefined;
+      const issues = await fetchIssues({ apiKey, apiBaseUrl, orgId, status, limit, offset, debug });
       return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
     }
     if (toolName === "view_issue") {
@@ -23430,6 +23696,70 @@ async function handleToolCall(req, rootOpts, extra) {
       const result = await updateIssueComment({ apiKey, apiBaseUrl, commentId, content, debug });
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
+    if (toolName === "view_action_item") {
+      let actionItemIds;
+      if (Array.isArray(args.action_item_ids)) {
+        actionItemIds = args.action_item_ids.map((id) => String(id).trim()).filter((id) => id);
+      } else if (args.action_item_id) {
+        actionItemIds = [String(args.action_item_id).trim()];
+      } else {
+        actionItemIds = [];
+      }
+      if (actionItemIds.length === 0) {
+        return { content: [{ type: "text", text: "action_item_id or action_item_ids is required" }], isError: true };
+      }
+      const actionItems = await fetchActionItem({ apiKey, apiBaseUrl, actionItemIds, debug });
+      if (actionItems.length === 0) {
+        return { content: [{ type: "text", text: "Action item(s) not found" }], isError: true };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(actionItems, null, 2) }] };
+    }
+    if (toolName === "list_action_items") {
+      const issueId = String(args.issue_id || "").trim();
+      if (!issueId) {
+        return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
+      }
+      const actionItems = await fetchActionItems({ apiKey, apiBaseUrl, issueId, debug });
+      return { content: [{ type: "text", text: JSON.stringify(actionItems, null, 2) }] };
+    }
+    if (toolName === "create_action_item") {
+      const issueId = String(args.issue_id || "").trim();
+      const rawTitle = String(args.title || "").trim();
+      if (!issueId) {
+        return { content: [{ type: "text", text: "issue_id is required" }], isError: true };
+      }
+      if (!rawTitle) {
+        return { content: [{ type: "text", text: "title is required" }], isError: true };
+      }
+      const title = interpretEscapes(rawTitle);
+      const rawDescription = args.description ? String(args.description) : undefined;
+      const description = rawDescription ? interpretEscapes(rawDescription) : undefined;
+      const sqlAction = args.sql_action !== undefined ? String(args.sql_action) : undefined;
+      const configs = Array.isArray(args.configs) ? args.configs : undefined;
+      const result = await createActionItem({ apiKey, apiBaseUrl, issueId, title, description, sqlAction, configs, debug });
+      return { content: [{ type: "text", text: JSON.stringify({ id: result }, null, 2) }] };
+    }
+    if (toolName === "update_action_item") {
+      const actionItemId = String(args.action_item_id || "").trim();
+      if (!actionItemId) {
+        return { content: [{ type: "text", text: "action_item_id is required" }], isError: true };
+      }
+      const rawTitle = args.title !== undefined ? String(args.title) : undefined;
+      const title = rawTitle !== undefined ? interpretEscapes(rawTitle) : undefined;
+      const rawDescription = args.description !== undefined ? String(args.description) : undefined;
+      const description = rawDescription !== undefined ? interpretEscapes(rawDescription) : undefined;
+      const isDone = args.is_done !== undefined ? Boolean(args.is_done) : undefined;
+      const status = args.status !== undefined ? String(args.status) : undefined;
+      const statusReason = args.status_reason !== undefined ? String(args.status_reason) : undefined;
+      if (title === undefined && description === undefined && isDone === undefined && status === undefined && statusReason === undefined) {
+        return { content: [{ type: "text", text: "At least one field to update is required (title, description, is_done, status, or status_reason)" }], isError: true };
+      }
+      if (status !== undefined && !["waiting_for_approval", "approved", "rejected"].includes(status)) {
+        return { content: [{ type: "text", text: "status must be 'waiting_for_approval', 'approved', or 'rejected'" }], isError: true };
+      }
+      await updateActionItem({ apiKey, apiBaseUrl, actionItemId, title, description, isDone, status, statusReason, debug });
+      return { content: [{ type: "text", text: JSON.stringify({ success: true }, null, 2) }] };
+    }
     throw new Error(`Unknown tool: ${toolName}`);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -23437,7 +23767,11 @@ async function handleToolCall(req, rootOpts, extra) {
   }
 }
 async function startMcpServer(rootOpts, extra) {
-  const server = new Server({ name: "postgresai-mcp", version: package_default2.version }, { capabilities: { tools: {} } });
+  const server = new Server({
+    name: "postgresai-mcp",
+    version: package_default2.version,
+    title: "PostgresAI MCP Server"
+  }, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
       tools: [
@@ -23447,6 +23781,10 @@ async function startMcpServer(rootOpts, extra) {
           inputSchema: {
             type: "object",
             properties: {
+              org_id: { type: "number", description: "Organization ID (optional, falls back to config)" },
+              status: { type: "string", description: "Filter by status: 'open', 'closed', or omit for all" },
+              limit: { type: "number", description: "Max number of issues to return (default: 20)" },
+              offset: { type: "number", description: "Number of issues to skip (default: 0)" },
               debug: { type: "boolean", description: "Enable verbose debug logs" }
             },
             additionalProperties: false
@@ -23535,47 +23873,130 @@ async function startMcpServer(rootOpts, extra) {
             required: ["comment_id", "content"],
             additionalProperties: false
           }
-        }
-      ]
-    };
-  });
-  server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    return handleToolCall(req, rootOpts, extra);
-  });
-  const transport = new StdioServerTransport;
-  await server.connect(transport);
-}
-
-// lib/issues.ts
-async function fetchIssues2(params) {
-  const { apiKey, apiBaseUrl, debug } = params;
-  if (!apiKey) {
-    throw new Error("API key is required");
-  }
-  const base = normalizeBaseUrl(apiBaseUrl);
-  const url = new URL(`${base}/issues`);
-  url.searchParams.set("select", "id,title,status,created_at");
-  const headers = {
-    "access-token": apiKey,
-    Prefer: "return=representation",
-    "Content-Type": "application/json",
-    Connection: "close"
-  };
-  if (debug) {
-    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
-    console.log(`Debug: Resolved API base URL: ${base}`);
-    console.log(`Debug: GET URL: ${url.toString()}`);
-    console.log(`Debug: Auth scheme: access-token`);
-    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
-  }
-  const response = await fetch(url.toString(), {
-    method: "GET",
-    headers
-  });
-  if (debug) {
-    console.log(`Debug: Response status: ${response.status}`);
-    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
-  }
+        },
+        {
+          name: "view_action_item",
+          description: "View action item(s) with all details. Supports single ID or multiple IDs.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              action_item_id: { type: "string", description: "Single action item ID (UUID)" },
+              action_item_ids: { type: "array", items: { type: "string" }, description: "Multiple action item IDs (UUIDs)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            additionalProperties: false
+          }
+        },
+        {
+          name: "list_action_items",
+          description: "List action items for an issue",
+          inputSchema: {
+            type: "object",
+            properties: {
+              issue_id: { type: "string", description: "Issue ID (UUID)" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["issue_id"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "create_action_item",
+          description: "Create a new action item for an issue",
+          inputSchema: {
+            type: "object",
+            properties: {
+              issue_id: { type: "string", description: "Issue ID (UUID)" },
+              title: { type: "string", description: "Action item title" },
+              description: { type: "string", description: "Detailed description" },
+              sql_action: { type: "string", description: "SQL command to execute, e.g. 'DROP INDEX CONCURRENTLY idx_unused;'" },
+              configs: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    parameter: { type: "string" },
+                    value: { type: "string" }
+                  },
+                  required: ["parameter", "value"]
+                },
+                description: "Configuration parameter changes"
+              },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["issue_id", "title"],
+            additionalProperties: false
+          }
+        },
+        {
+          name: "update_action_item",
+          description: "Update an action item: mark as done/not done, approve/reject, or edit title/description",
+          inputSchema: {
+            type: "object",
+            properties: {
+              action_item_id: { type: "string", description: "Action item ID (UUID)" },
+              title: { type: "string", description: "New title" },
+              description: { type: "string", description: "New description" },
+              is_done: { type: "boolean", description: "Mark as done (true) or not done (false)" },
+              status: { type: "string", description: "Approval status: 'waiting_for_approval', 'approved', or 'rejected'" },
+              status_reason: { type: "string", description: "Reason for approval/rejection" },
+              debug: { type: "boolean", description: "Enable verbose debug logs" }
+            },
+            required: ["action_item_id"],
+            additionalProperties: false
+          }
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    return handleToolCall(req, rootOpts, extra);
+  });
+  const transport = new StdioServerTransport;
+  await server.connect(transport);
+}
+
+// lib/issues.ts
+async function fetchIssues2(params) {
+  const { apiKey, apiBaseUrl, orgId, status, limit = 20, offset = 0, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issues`);
+  url.searchParams.set("select", "id,title,status,created_at");
+  url.searchParams.set("order", "id.desc");
+  url.searchParams.set("limit", String(limit));
+  url.searchParams.set("offset", String(offset));
+  if (typeof orgId === "number") {
+    url.searchParams.set("org_id", `eq.${orgId}`);
+  }
+  if (status === "open") {
+    url.searchParams.set("status", "eq.0");
+  } else if (status === "closed") {
+    url.searchParams.set("status", "eq.1");
+  }
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
   const data = await response.text();
   if (response.ok) {
     try {
@@ -23639,7 +24060,7 @@ async function fetchIssue2(params) {
   }
   const base = normalizeBaseUrl(apiBaseUrl);
   const url = new URL(`${base}/issues`);
-  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name");
+  url.searchParams.set("select", "id,title,description,status,created_at,author_display_name,action_items");
   url.searchParams.set("id", `eq.${issueId}`);
   url.searchParams.set("limit", "1");
   const headers = {
@@ -23667,11 +24088,20 @@ async function fetchIssue2(params) {
   if (response.ok) {
     try {
       const parsed = JSON.parse(data);
-      if (Array.isArray(parsed)) {
-        return parsed[0] ?? null;
-      } else {
-        return parsed;
+      const rawIssue = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (!rawIssue) {
+        return null;
       }
+      const actionItemsSummary = Array.isArray(rawIssue.action_items) ? rawIssue.action_items.map((item) => ({ id: item.id, title: item.title })) : [];
+      return {
+        id: rawIssue.id,
+        title: rawIssue.title,
+        description: rawIssue.description,
+        status: rawIssue.status,
+        created_at: rawIssue.created_at,
+        author_display_name: rawIssue.author_display_name,
+        action_items: actionItemsSummary
+      };
     } catch {
       throw new Error(`Failed to parse issue response: ${data}`);
     }
@@ -23910,6 +24340,243 @@ async function updateIssueComment2(params) {
     throw new Error(formatHttpError("Failed to update issue comment", response.status, data));
   }
 }
+async function fetchActionItem2(params) {
+  const { apiKey, apiBaseUrl, actionItemIds, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  const rawIds = Array.isArray(actionItemIds) ? actionItemIds : [actionItemIds];
+  const validIds = rawIds.filter((id) => id != null && typeof id === "string").map((id) => id.trim()).filter((id) => id.length > 0 && uuidPattern.test(id));
+  if (validIds.length === 0) {
+    throw new Error("actionItemId is required and must be a valid UUID");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  if (validIds.length === 1) {
+    url.searchParams.set("id", `eq.${validIds[0]}`);
+  } else {
+    url.searchParams.set("id", `in.(${validIds.join(",")})`);
+  }
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      const parsed = JSON.parse(data);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+      return parsed ? [parsed] : [];
+    } catch {
+      throw new Error(`Failed to parse action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action item", response.status, data));
+  }
+}
+async function fetchActionItems2(params) {
+  const { apiKey, apiBaseUrl, issueId, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/issue_action_items`);
+  url.searchParams.set("issue_id", `eq.${issueId.trim()}`);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: GET URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "GET",
+    headers
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(`Failed to parse action items response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to fetch action items", response.status, data));
+  }
+}
+async function createActionItem2(params) {
+  const { apiKey, apiBaseUrl, issueId, title, description, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!issueId) {
+    throw new Error("issueId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(issueId.trim())) {
+    throw new Error("issueId must be a valid UUID");
+  }
+  if (!title) {
+    throw new Error("title is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_create`);
+  const bodyObj = {
+    issue_id: issueId,
+    title
+  };
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  const data = await response.text();
+  if (response.ok) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      throw new Error(`Failed to parse create action item response: ${data}`);
+    }
+  } else {
+    throw new Error(formatHttpError("Failed to create action item", response.status, data));
+  }
+}
+async function updateActionItem2(params) {
+  const { apiKey, apiBaseUrl, actionItemId, title, description, isDone, status, statusReason, sqlAction, configs, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+  if (!actionItemId) {
+    throw new Error("actionItemId is required");
+  }
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidPattern.test(actionItemId.trim())) {
+    throw new Error("actionItemId must be a valid UUID");
+  }
+  const hasUpdateField = title !== undefined || description !== undefined || isDone !== undefined || status !== undefined || statusReason !== undefined || sqlAction !== undefined || configs !== undefined;
+  if (!hasUpdateField) {
+    throw new Error("At least one field to update is required");
+  }
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/issue_action_item_update`);
+  const bodyObj = {
+    action_item_id: actionItemId
+  };
+  if (title !== undefined) {
+    bodyObj.title = title;
+  }
+  if (description !== undefined) {
+    bodyObj.description = description;
+  }
+  if (isDone !== undefined) {
+    bodyObj.is_done = isDone;
+  }
+  if (status !== undefined) {
+    bodyObj.status = status;
+  }
+  if (statusReason !== undefined) {
+    bodyObj.status_reason = statusReason;
+  }
+  if (sqlAction !== undefined) {
+    bodyObj.sql_action = sqlAction;
+  }
+  if (configs !== undefined) {
+    bodyObj.configs = configs;
+  }
+  const body = JSON.stringify(bodyObj);
+  const headers = {
+    "access-token": apiKey,
+    Prefer: "return=representation",
+    "Content-Type": "application/json",
+    Connection: "close"
+  };
+  if (debug) {
+    const debugHeaders = { ...headers, "access-token": maskSecret(apiKey) };
+    console.log(`Debug: Resolved API base URL: ${base}`);
+    console.log(`Debug: POST URL: ${url.toString()}`);
+    console.log(`Debug: Auth scheme: access-token`);
+    console.log(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.log(`Debug: Request body: ${body}`);
+  }
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body
+  });
+  if (debug) {
+    console.log(`Debug: Response status: ${response.status}`);
+    console.log(`Debug: Response headers: ${JSON.stringify(Object.fromEntries(response.headers.entries()))}`);
+  }
+  if (!response.ok) {
+    const data = await response.text();
+    throw new Error(formatHttpError("Failed to update action item", response.status, data));
+  }
+}
 
 // lib/util.ts
 function maskSecret2(secret) {
@@ -23947,6 +24614,15 @@ import { URL as URL2, fileURLToPath } from "url";
 import * as fs3 from "fs";
 import * as path3 from "path";
 var DEFAULT_MONITORING_USER = "postgres_ai_mon";
+var KNOWN_PROVIDERS = ["self-managed", "supabase"];
+var SKIP_ROLE_CREATION_PROVIDERS = ["supabase"];
+var SKIP_ALTER_USER_PROVIDERS = ["supabase"];
+var SKIP_SEARCH_PATH_CHECK_PROVIDERS = ["supabase"];
+function validateProvider(provider) {
+  if (!provider || KNOWN_PROVIDERS.includes(provider))
+    return null;
+  return `Unknown provider "${provider}". Known providers: ${KNOWN_PROVIDERS.join(", ")}. Treating as self-managed.`;
+}
 function sslModeToConfig(mode) {
   if (mode.toLowerCase() === "disable")
     return false;
@@ -24261,6 +24937,7 @@ async function resolveMonitoringPassword(opts) {
 async function buildInitPlan(params) {
   const monitoringUser = params.monitoringUser || DEFAULT_MONITORING_USER;
   const database = params.database;
+  const provider = params.provider ?? "self-managed";
   const qRole = quoteIdent(monitoringUser);
   const qDb = quoteIdent(database);
   const qPw = quoteLiteral(params.monitoringPassword);
@@ -24270,7 +24947,8 @@ async function buildInitPlan(params) {
     ROLE_IDENT: qRole,
     DB_IDENT: qDb
   };
-  const roleStmt = `do $$ begin
+  if (!SKIP_ROLE_CREATION_PROVIDERS.includes(provider)) {
+    const roleStmt = `do $$ begin
   if not exists (select 1 from pg_catalog.pg_roles where rolname = ${qRoleNameLit}) then
     begin
       create user ${qRole} with password ${qPw};
@@ -24280,11 +24958,23 @@ async function buildInitPlan(params) {
   end if;
   alter user ${qRole} with password ${qPw};
 end $$;`;
-  const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
-  steps.push({ name: "01.role", sql: roleSql });
+    const roleSql = applyTemplate(loadSqlTemplate("01.role.sql"), { ...vars, ROLE_STMT: roleStmt });
+    steps.push({ name: "01.role", sql: roleSql });
+  }
+  let permissionsSql = applyTemplate(loadSqlTemplate("02.permissions.sql"), vars);
+  if (SKIP_ALTER_USER_PROVIDERS.includes(provider)) {
+    permissionsSql = permissionsSql.split(`
+`).filter((line) => {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("--") || trimmed === "")
+        return true;
+      return !/^\s*alter\s+user\s+/i.test(line);
+    }).join(`
+`);
+  }
   steps.push({
     name: "02.permissions",
-    sql: applyTemplate(loadSqlTemplate("02.permissions.sql"), vars)
+    sql: permissionsSql
   });
   steps.push({
     name: "05.helpers",
@@ -24301,25 +24991,413 @@ end $$;`;
       optional: true
     });
   }
-  return { monitoringUser, database, steps };
+  return { monitoringUser, database, steps };
+}
+async function applyInitPlan(params) {
+  const applied = [];
+  const skippedOptional = [];
+  const executeStep = async (step) => {
+    await params.client.query("begin;");
+    try {
+      await params.client.query(step.sql, step.params);
+      await params.client.query("commit;");
+    } catch (e) {
+      try {
+        await params.client.query("rollback;");
+      } catch {}
+      throw e;
+    }
+  };
+  for (const step of params.plan.steps.filter((s) => !s.optional)) {
+    try {
+      await executeStep(step);
+      applied.push(step.name);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      const errAny = e;
+      const wrapped = new Error(`Failed at step "${step.name}": ${msg}`);
+      const pgErrorFields = [
+        "code",
+        "detail",
+        "hint",
+        "position",
+        "internalPosition",
+        "internalQuery",
+        "where",
+        "schema",
+        "table",
+        "column",
+        "dataType",
+        "constraint",
+        "file",
+        "line",
+        "routine"
+      ];
+      if (errAny && typeof errAny === "object") {
+        for (const field of pgErrorFields) {
+          if (errAny[field] !== undefined)
+            wrapped[field] = errAny[field];
+        }
+      }
+      if (e instanceof Error && e.stack) {
+        wrapped.stack = e.stack;
+      }
+      throw wrapped;
+    }
+  }
+  for (const step of params.plan.steps.filter((s) => s.optional)) {
+    try {
+      await executeStep(step);
+      applied.push(step.name);
+    } catch {
+      skippedOptional.push(step.name);
+    }
+  }
+  return { applied, skippedOptional };
+}
+async function verifyInitSetup(params) {
+  await params.client.query("begin isolation level repeatable read;");
+  try {
+    const missingRequired = [];
+    const missingOptional = [];
+    const role = params.monitoringUser;
+    const db = params.database;
+    const provider = params.provider ?? "self-managed";
+    const roleRes = await params.client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [role]);
+    const roleExists = (roleRes.rowCount ?? 0) > 0;
+    if (!roleExists) {
+      missingRequired.push(`role "${role}" does not exist`);
+      return { ok: false, missingRequired, missingOptional };
+    }
+    const connectRes = await params.client.query("select has_database_privilege($1, $2, 'CONNECT') as ok", [role, db]);
+    if (!connectRes.rows?.[0]?.ok) {
+      missingRequired.push(`CONNECT on database "${db}"`);
+    }
+    const pgMonitorRes = await params.client.query("select pg_has_role($1, 'pg_monitor', 'member') as ok", [role]);
+    if (!pgMonitorRes.rows?.[0]?.ok) {
+      missingRequired.push("membership in role pg_monitor");
+    }
+    const pgIndexRes = await params.client.query("select has_table_privilege($1, 'pg_catalog.pg_index', 'SELECT') as ok", [role]);
+    if (!pgIndexRes.rows?.[0]?.ok) {
+      missingRequired.push("SELECT on pg_catalog.pg_index");
+    }
+    const schemaExistsRes = await params.client.query("select has_schema_privilege($1, 'postgres_ai', 'USAGE') as ok", [role]);
+    if (!schemaExistsRes.rows?.[0]?.ok) {
+      missingRequired.push("USAGE on schema postgres_ai");
+    }
+    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
+    if (!viewExistsRes.rows?.[0]?.ok) {
+      missingRequired.push("view postgres_ai.pg_statistic exists");
+    } else {
+      const viewPrivRes = await params.client.query("select has_table_privilege($1, 'postgres_ai.pg_statistic', 'SELECT') as ok", [role]);
+      if (!viewPrivRes.rows?.[0]?.ok) {
+        missingRequired.push("SELECT on view postgres_ai.pg_statistic");
+      }
+    }
+    const schemaUsageRes = await params.client.query("select has_schema_privilege($1, 'public', 'USAGE') as ok", [role]);
+    if (!schemaUsageRes.rows?.[0]?.ok) {
+      missingRequired.push("USAGE on schema public");
+    }
+    if (!SKIP_SEARCH_PATH_CHECK_PROVIDERS.includes(provider)) {
+      const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
+      const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
+      const spLine = Array.isArray(rolconfig) ? rolconfig.find((v) => String(v).startsWith("search_path=")) : undefined;
+      if (typeof spLine !== "string" || !spLine) {
+        missingRequired.push("role search_path is set");
+      } else {
+        const sp = spLine.toLowerCase();
+        if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
+          missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
+        }
+      }
+    }
+    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)");
+    }
+    if (params.includeOptionalPermissions) {
+      {
+        const extRes = await params.client.query("select 1 from pg_extension where extname = 'rds_tools'");
+        if ((extRes.rowCount ?? 0) === 0) {
+          missingOptional.push("extension rds_tools");
+        } else {
+          const fnRes = await params.client.query("select has_function_privilege($1, 'rds_tools.pg_ls_multixactdir()', 'EXECUTE') as ok", [role]);
+          if (!fnRes.rows?.[0]?.ok) {
+            missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
+          }
+        }
+      }
+      const optionalFns = [
+        "pg_catalog.pg_stat_file(text)",
+        "pg_catalog.pg_stat_file(text, boolean)",
+        "pg_catalog.pg_ls_dir(text)",
+        "pg_catalog.pg_ls_dir(text, boolean, boolean)"
+      ];
+      for (const fn of optionalFns) {
+        const fnRes = await params.client.query("select has_function_privilege($1, $2, 'EXECUTE') as ok", [role, fn]);
+        if (!fnRes.rows?.[0]?.ok) {
+          missingOptional.push(`EXECUTE on ${fn}`);
+        }
+      }
+    }
+    return { ok: missingRequired.length === 0, missingRequired, missingOptional };
+  } finally {
+    try {
+      await params.client.query("rollback;");
+    } catch {}
+  }
+}
+
+// lib/supabase.ts
+var SUPABASE_API_BASE = "https://api.supabase.com";
+function isValidProjectRef(ref) {
+  return /^[a-z0-9]{10,30}$/i.test(ref);
+}
+
+class SupabaseClient {
+  config;
+  constructor(config2) {
+    if (!config2.projectRef) {
+      throw new Error("Supabase project reference is required");
+    }
+    if (!config2.accessToken) {
+      throw new Error("Supabase access token is required");
+    }
+    if (!isValidProjectRef(config2.projectRef)) {
+      throw new Error(`Invalid Supabase project reference format: "${config2.projectRef}". Expected 10-30 alphanumeric characters.`);
+    }
+    this.config = config2;
+  }
+  async query(sql, readOnly = false) {
+    const url = `${SUPABASE_API_BASE}/v1/projects/${encodeURIComponent(this.config.projectRef)}/database/query`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.accessToken}`
+      },
+      body: JSON.stringify({
+        query: sql,
+        read_only: readOnly
+      })
+    });
+    const body = await response.text();
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      throw this.createPgError({
+        message: `Supabase API returned non-JSON response: ${body.slice(0, 200)}`,
+        httpStatus: response.status
+      });
+    }
+    if (!response.ok) {
+      throw this.parseApiError(data, response.status);
+    }
+    if (data && typeof data === "object" && "error" in data && data.error) {
+      throw this.parseApiError(data, response.status);
+    }
+    const rows = Array.isArray(data) ? data : [];
+    return {
+      rows,
+      rowCount: rows.length
+    };
+  }
+  async testConnection() {
+    const result = await this.query("SELECT current_database() as db, version() as version", true);
+    const row = result.rows[0] ?? {};
+    return {
+      database: String(row.db ?? ""),
+      version: String(row.version ?? "")
+    };
+  }
+  async getCurrentDatabase() {
+    const result = await this.query("SELECT current_database() as db", true);
+    const row = result.rows[0] ?? {};
+    return String(row.db ?? "");
+  }
+  parseApiError(data, httpStatus) {
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      const errObj = "error" in data && data.error ? data.error : data;
+      const pgCode = this.extractPgErrorCode(errObj);
+      const message = this.extractErrorMessage(errObj);
+      const detail = this.extractField(errObj, ["details", "detail"]);
+      const hint = this.extractField(errObj, ["hint"]);
+      return this.createPgError({
+        message,
+        code: pgCode,
+        detail,
+        hint,
+        httpStatus,
+        supabaseErrorCode: typeof errObj === "object" && errObj && "code" in errObj ? String(errObj.code ?? "") : undefined
+      });
+    }
+    return this.createPgError({
+      message: `Supabase API error (HTTP ${httpStatus})`,
+      httpStatus
+    });
+  }
+  extractPgErrorCode(errObj) {
+    if (!errObj || typeof errObj !== "object")
+      return;
+    const obj = errObj;
+    if (typeof obj.code === "string") {
+      const code = obj.code;
+      if (/^\d{5}$/.test(code)) {
+        return code;
+      }
+      return this.mapSupabaseCodeToPg(code);
+    }
+    return;
+  }
+  mapSupabaseCodeToPg(code) {
+    const mapping = {
+      PGRST301: "28000",
+      PGRST302: "28P01",
+      "42501": "42501",
+      PGRST000: "42501",
+      "42601": "42601",
+      "42P01": "42P01",
+      PGRST200: "42P01",
+      "42883": "42883",
+      "08000": "08000",
+      "08003": "08003",
+      "08006": "08006",
+      "42710": "42710"
+    };
+    return mapping[code];
+  }
+  extractErrorMessage(errObj) {
+    if (!errObj || typeof errObj !== "object") {
+      return "Unknown Supabase API error";
+    }
+    const obj = errObj;
+    for (const field of ["message", "error", "msg", "description"]) {
+      if (typeof obj[field] === "string" && obj[field]) {
+        return obj[field];
+      }
+    }
+    if (obj.error && typeof obj.error === "object") {
+      return this.extractErrorMessage(obj.error);
+    }
+    return "Unknown Supabase API error";
+  }
+  extractField(errObj, fieldNames) {
+    if (!errObj || typeof errObj !== "object")
+      return;
+    const obj = errObj;
+    for (const field of fieldNames) {
+      if (typeof obj[field] === "string" && obj[field]) {
+        return obj[field];
+      }
+    }
+    return;
+  }
+  createPgError(opts) {
+    const err = new Error(opts.message);
+    if (opts.code)
+      err.code = opts.code;
+    if (opts.detail)
+      err.detail = opts.detail;
+    if (opts.hint)
+      err.hint = opts.hint;
+    if (opts.httpStatus)
+      err.httpStatus = opts.httpStatus;
+    if (opts.supabaseErrorCode)
+      err.supabaseErrorCode = opts.supabaseErrorCode;
+    return err;
+  }
+}
+async function fetchPoolerDatabaseUrl(config2, username) {
+  const url = `${SUPABASE_API_BASE}/v1/projects/${encodeURIComponent(config2.projectRef)}/config/database/pooler`;
+  try {
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${config2.accessToken}`
+      }
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    if (Array.isArray(data) && data.length > 0) {
+      const pooler = data[0];
+      if (pooler.db_host && pooler.db_port && pooler.db_name) {
+        return `postgresql://${username}@${pooler.db_host}:${pooler.db_port}/${pooler.db_name}`;
+      }
+      if (typeof pooler.connection_string === "string") {
+        try {
+          const connUrl = new URL(pooler.connection_string);
+          const portPart = connUrl.port ? `:${connUrl.port}` : "";
+          return `postgresql://${username}@${connUrl.hostname}${portPart}${connUrl.pathname}`;
+        } catch {
+          return null;
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
 }
-async function applyInitPlan(params) {
+function resolveSupabaseConfig(opts) {
+  const accessToken = opts.accessToken?.trim() || process.env.SUPABASE_ACCESS_TOKEN?.trim() || "";
+  const projectRef = opts.projectRef?.trim() || process.env.SUPABASE_PROJECT_REF?.trim() || "";
+  if (!accessToken) {
+    throw new Error(`Supabase access token is required.
+` + `Provide it via --supabase-access-token or SUPABASE_ACCESS_TOKEN environment variable.
+` + "Generate a token at: https://supabase.com/dashboard/account/tokens");
+  }
+  if (!projectRef) {
+    throw new Error(`Supabase project reference is required.
+` + `Provide it via --supabase-project-ref or SUPABASE_PROJECT_REF environment variable.
+` + "Find your project ref in the Supabase dashboard URL: https://supabase.com/dashboard/project/<ref>");
+  }
+  return { accessToken, projectRef };
+}
+function extractProjectRefFromUrl(dbUrl) {
+  try {
+    const url = new URL(dbUrl);
+    const host = url.hostname;
+    const match = host.match(/^(?:db\.)?([^.]+)\.supabase\.co$/i);
+    if (match && match[1]) {
+      return match[1];
+    }
+    if (host.includes("pooler.supabase.com")) {
+      const username = url.username;
+      const userMatch = username.match(/^postgres\.([a-z0-9]+)$/i);
+      if (userMatch && userMatch[1]) {
+        return userMatch[1];
+      }
+    }
+    const poolerMatch = host.match(/^([a-z0-9]+)\.pooler\.supabase\.com$/i);
+    if (poolerMatch && poolerMatch[1] && !poolerMatch[1].startsWith("aws-")) {
+      return poolerMatch[1];
+    }
+    return;
+  } catch {
+    return;
+  }
+}
+async function applyInitPlanViaSupabase(params) {
   const applied = [];
   const skippedOptional = [];
   const executeStep = async (step) => {
-    await params.client.query("begin;");
-    try {
-      await params.client.query(step.sql, step.params);
-      await params.client.query("commit;");
-    } catch (e) {
-      try {
-        await params.client.query("rollback;");
-      } catch {}
-      throw e;
-    }
+    const wrappedSql = `BEGIN;
+${step.sql}
+COMMIT;`;
+    await params.client.query(wrappedSql, false);
   };
   for (const step of params.plan.steps.filter((s) => !s.optional)) {
     try {
+      if (params.verbose) {
+        console.log(`Executing step: ${step.name}`);
+      }
       await executeStep(step);
       applied.push(step.name);
     } catch (e) {
@@ -24341,12 +25419,13 @@ async function applyInitPlan(params) {
         "constraint",
         "file",
         "line",
-        "routine"
+        "routine",
+        "httpStatus",
+        "supabaseErrorCode"
       ];
-      if (errAny && typeof errAny === "object") {
-        for (const field of pgErrorFields) {
-          if (errAny[field] !== undefined)
-            wrapped[field] = errAny[field];
+      for (const field of pgErrorFields) {
+        if (errAny[field] !== undefined) {
+          wrapped[field] = errAny[field];
         }
       }
       if (e instanceof Error && e.stack) {
@@ -24357,6 +25436,9 @@ async function applyInitPlan(params) {
   }
   for (const step of params.plan.steps.filter((s) => s.optional)) {
     try {
+      if (params.verbose) {
+        console.log(`Executing optional step: ${step.name}`);
+      }
       await executeStep(step);
       applied.push(step.name);
     } catch {
@@ -24365,98 +25447,133 @@ async function applyInitPlan(params) {
   }
   return { applied, skippedOptional };
 }
-async function verifyInitSetup(params) {
-  await params.client.query("begin isolation level repeatable read;");
-  try {
-    const missingRequired = [];
-    const missingOptional = [];
-    const role = params.monitoringUser;
-    const db = params.database;
-    const roleRes = await params.client.query("select 1 from pg_catalog.pg_roles where rolname = $1", [role]);
-    const roleExists = (roleRes.rowCount ?? 0) > 0;
-    if (!roleExists) {
-      missingRequired.push(`role "${role}" does not exist`);
-      return { ok: false, missingRequired, missingOptional };
-    }
-    const connectRes = await params.client.query("select has_database_privilege($1, $2, 'CONNECT') as ok", [role, db]);
-    if (!connectRes.rows?.[0]?.ok) {
-      missingRequired.push(`CONNECT on database "${db}"`);
-    }
-    const pgMonitorRes = await params.client.query("select pg_has_role($1, 'pg_monitor', 'member') as ok", [role]);
-    if (!pgMonitorRes.rows?.[0]?.ok) {
-      missingRequired.push("membership in role pg_monitor");
-    }
-    const pgIndexRes = await params.client.query("select has_table_privilege($1, 'pg_catalog.pg_index', 'SELECT') as ok", [role]);
-    if (!pgIndexRes.rows?.[0]?.ok) {
-      missingRequired.push("SELECT on pg_catalog.pg_index");
-    }
-    const schemaExistsRes = await params.client.query("select has_schema_privilege($1, 'postgres_ai', 'USAGE') as ok", [role]);
-    if (!schemaExistsRes.rows?.[0]?.ok) {
+async function verifyInitSetupViaSupabase(params) {
+  const missingRequired = [];
+  const missingOptional = [];
+  const role = params.monitoringUser;
+  const db = params.database;
+  if (!isValidIdentifier(role)) {
+    throw new Error(`Invalid monitoring user name: "${role}". Must be a valid PostgreSQL identifier (letters, digits, underscores, max 63 chars, starting with letter or underscore).`);
+  }
+  const roleRes = await params.client.query(`SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = '${escapeLiteral2(role)}'`, true);
+  const roleExists = roleRes.rowCount > 0;
+  if (!roleExists) {
+    missingRequired.push(`role "${role}" does not exist`);
+    return { ok: false, missingRequired, missingOptional };
+  }
+  const connectRes = await params.client.query(`SELECT has_database_privilege('${escapeLiteral2(role)}', '${escapeLiteral2(db)}', 'CONNECT') as ok`, true);
+  if (!connectRes.rows?.[0]?.ok) {
+    missingRequired.push(`CONNECT on database "${db}"`);
+  }
+  const pgMonitorRes = await params.client.query(`SELECT pg_has_role('${escapeLiteral2(role)}', 'pg_monitor', 'member') as ok`, true);
+  if (!pgMonitorRes.rows?.[0]?.ok) {
+    missingRequired.push("membership in role pg_monitor");
+  }
+  const pgIndexRes = await params.client.query(`SELECT has_table_privilege('${escapeLiteral2(role)}', 'pg_catalog.pg_index', 'SELECT') as ok`, true);
+  if (!pgIndexRes.rows?.[0]?.ok) {
+    missingRequired.push("SELECT on pg_catalog.pg_index");
+  }
+  const schemaExistsRes = await params.client.query("SELECT nspname FROM pg_namespace WHERE nspname = 'postgres_ai'", true);
+  if (schemaExistsRes.rowCount === 0) {
+    missingRequired.push("schema postgres_ai exists");
+  } else {
+    const schemaPrivRes = await params.client.query(`SELECT has_schema_privilege('${escapeLiteral2(role)}', 'postgres_ai', 'USAGE') as ok`, true);
+    if (!schemaPrivRes.rows?.[0]?.ok) {
       missingRequired.push("USAGE on schema postgres_ai");
     }
-    const viewExistsRes = await params.client.query("select to_regclass('postgres_ai.pg_statistic') is not null as ok");
-    if (!viewExistsRes.rows?.[0]?.ok) {
-      missingRequired.push("view postgres_ai.pg_statistic exists");
-    } else {
-      const viewPrivRes = await params.client.query("select has_table_privilege($1, 'postgres_ai.pg_statistic', 'SELECT') as ok", [role]);
-      if (!viewPrivRes.rows?.[0]?.ok) {
-        missingRequired.push("SELECT on view postgres_ai.pg_statistic");
-      }
+  }
+  const viewExistsRes = await params.client.query("SELECT to_regclass('postgres_ai.pg_statistic') IS NOT NULL as ok", true);
+  if (!viewExistsRes.rows?.[0]?.ok) {
+    missingRequired.push("view postgres_ai.pg_statistic exists");
+  } else {
+    const viewPrivRes = await params.client.query(`SELECT has_table_privilege('${escapeLiteral2(role)}', 'postgres_ai.pg_statistic', 'SELECT') as ok`, true);
+    if (!viewPrivRes.rows?.[0]?.ok) {
+      missingRequired.push("SELECT on view postgres_ai.pg_statistic");
     }
-    const schemaUsageRes = await params.client.query("select has_schema_privilege($1, 'public', 'USAGE') as ok", [role]);
+  }
+  const publicSchemaExistsRes = await params.client.query("SELECT nspname FROM pg_namespace WHERE nspname = 'public'", true);
+  if (publicSchemaExistsRes.rowCount === 0) {
+    missingRequired.push("schema public exists");
+  } else {
+    const schemaUsageRes = await params.client.query(`SELECT has_schema_privilege('${escapeLiteral2(role)}', 'public', 'USAGE') as ok`, true);
     if (!schemaUsageRes.rows?.[0]?.ok) {
       missingRequired.push("USAGE on schema public");
     }
-    const rolcfgRes = await params.client.query("select rolconfig from pg_catalog.pg_roles where rolname = $1", [role]);
-    const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
-    const spLine = Array.isArray(rolconfig) ? rolconfig.find((v) => String(v).startsWith("search_path=")) : undefined;
-    if (typeof spLine !== "string" || !spLine) {
-      missingRequired.push("role search_path is set");
-    } else {
-      const sp = spLine.toLowerCase();
-      if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
-        missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
-      }
+  }
+  const rolcfgRes = await params.client.query(`SELECT rolconfig FROM pg_catalog.pg_roles WHERE rolname = '${escapeLiteral2(role)}'`, true);
+  const rolconfig = rolcfgRes.rows?.[0]?.rolconfig;
+  const spLine = Array.isArray(rolconfig) ? rolconfig.find((v) => String(v).startsWith("search_path=")) : undefined;
+  if (typeof spLine !== "string" || !spLine) {
+    missingRequired.push("role search_path is set");
+  } else {
+    const sp = spLine.toLowerCase();
+    if (!sp.includes("postgres_ai") || !sp.includes("public") || !sp.includes("pg_catalog")) {
+      missingRequired.push("role search_path includes postgres_ai, public and pg_catalog");
     }
-    const explainFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.explain_generic(text, text, text)', 'EXECUTE') as ok", [role]);
+  }
+  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 tableDescribeFnRes = await params.client.query("select has_function_privilege($1, 'postgres_ai.table_describe(text)', 'EXECUTE') as ok", [role]);
+  }
+  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");
+  } else {
+    const tableDescribeFnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'postgres_ai.table_describe(text)', 'EXECUTE') as ok`, true);
     if (!tableDescribeFnRes.rows?.[0]?.ok) {
       missingRequired.push("EXECUTE on postgres_ai.table_describe(text)");
     }
-    if (params.includeOptionalPermissions) {
-      {
-        const extRes = await params.client.query("select 1 from pg_extension where extname = 'rds_tools'");
-        if ((extRes.rowCount ?? 0) === 0) {
-          missingOptional.push("extension rds_tools");
-        } else {
-          const fnRes = await params.client.query("select has_function_privilege($1, 'rds_tools.pg_ls_multixactdir()', 'EXECUTE') as ok", [role]);
-          if (!fnRes.rows?.[0]?.ok) {
-            missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
-          }
+  }
+  if (params.includeOptionalPermissions) {
+    const extRes = await params.client.query("SELECT 1 FROM pg_extension WHERE extname = 'rds_tools'", true);
+    if (extRes.rowCount === 0) {
+      missingOptional.push("extension rds_tools");
+    } else {
+      try {
+        const fnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', 'rds_tools.pg_ls_multixactdir()', 'EXECUTE') as ok`, true);
+        if (!fnRes.rows?.[0]?.ok) {
+          missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
         }
+      } catch {
+        missingOptional.push("EXECUTE on rds_tools.pg_ls_multixactdir()");
       }
-      const optionalFns = [
-        "pg_catalog.pg_stat_file(text)",
-        "pg_catalog.pg_stat_file(text, boolean)",
-        "pg_catalog.pg_ls_dir(text)",
-        "pg_catalog.pg_ls_dir(text, boolean, boolean)"
-      ];
-      for (const fn of optionalFns) {
-        const fnRes = await params.client.query("select has_function_privilege($1, $2, 'EXECUTE') as ok", [role, fn]);
+    }
+    const optionalFns = [
+      "pg_catalog.pg_stat_file(text)",
+      "pg_catalog.pg_stat_file(text, boolean)",
+      "pg_catalog.pg_ls_dir(text)",
+      "pg_catalog.pg_ls_dir(text, boolean, boolean)"
+    ];
+    for (const fn of optionalFns) {
+      try {
+        const fnRes = await params.client.query(`SELECT has_function_privilege('${escapeLiteral2(role)}', '${fn}', 'EXECUTE') as ok`, true);
         if (!fnRes.rows?.[0]?.ok) {
           missingOptional.push(`EXECUTE on ${fn}`);
         }
+      } catch {
+        missingOptional.push(`EXECUTE on ${fn}`);
       }
     }
-    return { ok: missingRequired.length === 0, missingRequired, missingOptional };
-  } finally {
-    try {
-      await params.client.query("rollback;");
-    } catch {}
   }
+  return {
+    ok: missingRequired.length === 0,
+    missingRequired,
+    missingOptional
+  };
+}
+function isValidIdentifier(name) {
+  return /^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(name);
+}
+function escapeLiteral2(value) {
+  if (value.includes("\x00")) {
+    throw new Error("SQL literal cannot contain null bytes");
+  }
+  return value.replace(/'/g, "''");
 }
 
 // lib/pkce.ts
@@ -24958,17 +26075,17 @@ where
     statement_timeout_seconds: 300
   },
   pg_invalid_indexes: {
-    description: "This metric identifies invalid indexes in the database. It provides insights into the number of invalid indexes and their details. This metric helps administrators identify and fix invalid indexes to improve database performance.",
+    description: "This metric identifies invalid indexes in the database with decision tree data for remediation. It provides insights into whether to DROP (if duplicate exists), RECREATE (if backs constraint), or flag as UNCERTAIN (if additional RCA is needed to check query plans). Decision tree: 1) Valid duplicate exists -> DROP, 2) Backs PK/UNIQUE constraint -> RECREATE, 3) Table < 10K rows -> RECREATE (small tables rebuild quickly, typically under 1 second), 4) Otherwise -> UNCERTAIN (need query plan analysis to assess impact).",
     sqls: {
       11: `with fk_indexes as ( /* pgwatch_generated */
   select
-    schemaname as tag_schema_name,
-    (indexrelid::regclass)::text as tag_index_name,
-    (relid::regclass)::text as tag_table_name,
-    (confrelid::regclass)::text as tag_fk_table_ref,
-    array_to_string(indclass, ', ') as tag_opclasses
-  from
-    pg_stat_all_indexes
+    schemaname as schema_name,
+    indexrelid,
+    (indexrelid::regclass)::text as index_name,
+    (relid::regclass)::text as table_name,
+    (confrelid::regclass)::text as fk_table_ref,
+    array_to_string(indclass, ', ') as opclasses
+  from pg_stat_all_indexes
   join pg_index using (indexrelid)
   left join pg_constraint
     on array_to_string(indkey, ',') = array_to_string(conkey, ',')
@@ -24977,37 +26094,58 @@ where
       and contype = 'f'
   where idx_scan = 0
     and indisunique is false
-    and conkey is not null --conkey is not null then true else false end as is_fk_idx
-), data as (
+    and conkey is not null
+),
+-- Find valid indexes that could be duplicates (same table, same columns)
+valid_duplicates as (
+  select
+    inv.indexrelid as invalid_indexrelid,
+    val.indexrelid as valid_indexrelid,
+    (val.indexrelid::regclass)::text as valid_index_name,
+    pg_get_indexdef(val.indexrelid) as valid_index_definition
+  from pg_index inv
+  join pg_index val on inv.indrelid = val.indrelid  -- same table
+    and inv.indkey = val.indkey  -- same columns (in same order)
+    and inv.indexrelid != val.indexrelid  -- different index
+    and val.indisvalid = true  -- valid index
+  where inv.indisvalid = false
+),
+data as (
   select
     pci.relname as tag_index_name,
     pn.nspname as tag_schema_name,
     pct.relname as tag_table_name,
-    quote_ident(pn.nspname) as tag_schema_name,
-    quote_ident(pci.relname) as tag_index_name,
-    quote_ident(pct.relname) as tag_table_name,
     coalesce(nullif(quote_ident(pn.nspname), 'public') || '.', '') || quote_ident(pct.relname) as tag_relation_name,
     pg_get_indexdef(pidx.indexrelid) as index_definition,
-    pg_relation_size(pidx.indexrelid) index_size_bytes,
+    pg_relation_size(pidx.indexrelid) as index_size_bytes,
+    -- Constraint info
+    pidx.indisprimary as is_pk,
+    pidx.indisunique as is_unique,
+    con.conname as constraint_name,
+    -- Table row estimate
+    pct.reltuples::bigint as table_row_estimate,
+    -- Valid duplicate check
+    (vd.valid_indexrelid is not null) as has_valid_duplicate,
+    vd.valid_index_name,
+    vd.valid_index_definition,
+    -- FK support check
     ((
       select count(1)
       from fk_indexes fi
-      where
-        fi.tag_fk_table_ref = pct.relname
-        and fi.tag_opclasses like (array_to_string(pidx.indclass, ', ') || '%')
+      where fi.fk_table_ref = pct.relname
+        and fi.opclasses like (array_to_string(pidx.indclass, ', ') || '%')
     ) > 0)::int as supports_fk
   from pg_index pidx
-  join pg_class as pci on pci.oid = pidx.indexrelid
-  join pg_class as pct on pct.oid = pidx.indrelid
+  join pg_class pci on pci.oid = pidx.indexrelid
+  join pg_class pct on pct.oid = pidx.indrelid
   left join pg_namespace pn on pn.oid = pct.relnamespace
+  left join pg_constraint con on con.conindid = pidx.indexrelid
+  left join valid_duplicates vd on vd.invalid_indexrelid = pidx.indexrelid
   where pidx.indisvalid = false
-), data_total as (
-    select
-      sum(index_size_bytes) as index_size_bytes_sum
-    from data
-), num_data as (
+),
+num_data as (
   select
-    row_number() over () num,
+    row_number() over () as num,
     data.*
   from data
 )
@@ -25626,7 +26764,14 @@ async function getInvalidIndexes(client, pgMajorVersion = 16) {
       index_size_bytes: indexSizeBytes,
       index_size_pretty: formatBytes(indexSizeBytes),
       index_definition: String(transformed.index_definition || ""),
-      supports_fk: toBool(transformed.supports_fk)
+      supports_fk: toBool(transformed.supports_fk),
+      is_pk: toBool(transformed.is_pk),
+      is_unique: toBool(transformed.is_unique),
+      constraint_name: transformed.constraint_name ? String(transformed.constraint_name) : null,
+      table_row_estimate: parseInt(String(transformed.table_row_estimate || 0), 10),
+      has_valid_duplicate: toBool(transformed.has_valid_duplicate),
+      valid_duplicate_name: transformed.valid_index_name ? String(transformed.valid_index_name) : null,
+      valid_duplicate_definition: transformed.valid_index_definition ? String(transformed.valid_index_definition) : null
     };
   });
 }
@@ -26715,7 +27860,7 @@ program2.command("set-default-project <project>").description("store default pro
   writeConfig({ defaultProject: value });
   console.log(`Default project saved: ${value}`);
 });
-program2.command("prepare-db [conn]").description("prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)").option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)").option("-h, --host <host>", "PostgreSQL host (psql-like)").option("-p, --port <port>", "PostgreSQL port (psql-like)").option("-U, --username <username>", "PostgreSQL user (psql-like)").option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)").option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)").option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER).option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)").option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false).option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false).option("--reset-password", "Reset monitoring role password only (no other changes)", false).option("--print-sql", "Print SQL plan and exit (no changes applied)", false).option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false).addHelpText("after", [
+program2.command("prepare-db [conn]").description("prepare database for monitoring: create monitoring user, required view(s), and grant permissions (idempotent)").option("--db-url <url>", "PostgreSQL connection URL (admin) to run the setup against (deprecated; pass it as positional arg)").option("-h, --host <host>", "PostgreSQL host (psql-like)").option("-p, --port <port>", "PostgreSQL port (psql-like)").option("-U, --username <username>", "PostgreSQL user (psql-like)").option("-d, --dbname <dbname>", "PostgreSQL database name (psql-like)").option("--admin-password <password>", "Admin connection password (otherwise uses PGPASSWORD if set)").option("--monitoring-user <name>", "Monitoring role name to create/update", DEFAULT_MONITORING_USER).option("--password <password>", "Monitoring role password (overrides PGAI_MON_PASSWORD)").option("--skip-optional-permissions", "Skip optional permissions (RDS/self-managed extras)", false).option("--provider <provider>", "Database provider (e.g., supabase). Affects which steps are executed.").option("--verify", "Verify that monitoring role/permissions are in place (no changes)", false).option("--reset-password", "Reset monitoring role password only (no other changes)", false).option("--print-sql", "Print SQL plan and exit (no changes applied)", false).option("--print-password", "Print generated monitoring password (DANGEROUS in CI logs)", false).option("--supabase", "Use Supabase Management API instead of direct PostgreSQL connection", false).option("--supabase-access-token <token>", "Supabase Management API access token (or SUPABASE_ACCESS_TOKEN env)").option("--supabase-project-ref <ref>", "Supabase project reference (or SUPABASE_PROJECT_REF env)").option("--json", "Output result as JSON (machine-readable)", false).addHelpText("after", [
   "",
   "Examples:",
   "  postgresai prepare-db postgresql://admin@host:5432/dbname",
@@ -26751,21 +27896,60 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
   "  postgresai prepare-db <conn> --reset-password --password '...'",
   "",
   "Offline SQL plan (no DB connection):",
-  "  postgresai prepare-db --print-sql"
+  "  postgresai prepare-db --print-sql",
+  "",
+  "Supabase mode (use Management API instead of direct connection):",
+  "  postgresai prepare-db --supabase --supabase-project-ref <ref>",
+  "  SUPABASE_ACCESS_TOKEN=... postgresai prepare-db --supabase --supabase-project-ref <ref>",
+  "",
+  "  Generate a token at: https://supabase.com/dashboard/account/tokens",
+  "  Find your project ref in: https://supabase.com/dashboard/project/<ref>",
+  "",
+  "Provider-specific behavior (for direct connections):",
+  "  --provider supabase    Skip role creation (create user in Supabase dashboard)",
+  "                         Skip ALTER USER (restricted by Supabase)"
 ].join(`
 `)).action(async (conn, opts, cmd) => {
-  if (opts.verify && opts.resetPassword) {
-    console.error("\u2717 Provide only one of --verify or --reset-password");
+  const jsonOutput = opts.json;
+  const outputJson = (data) => {
+    console.log(JSON.stringify(data, null, 2));
+  };
+  const outputError = (error2) => {
+    if (jsonOutput) {
+      outputJson({
+        success: false,
+        mode: opts.supabase ? "supabase" : "direct",
+        error: error2
+      });
+    } else {
+      console.error(`Error: prepare-db${opts.supabase ? " (Supabase)" : ""}: ${error2.message}`);
+      if (error2.step)
+        console.error(`  Step: ${error2.step}`);
+      if (error2.code)
+        console.error(`  Code: ${error2.code}`);
+      if (error2.detail)
+        console.error(`  Detail: ${error2.detail}`);
+      if (error2.hint)
+        console.error(`  Hint: ${error2.hint}`);
+      if (error2.httpStatus)
+        console.error(`  HTTP Status: ${error2.httpStatus}`);
+    }
     process.exitCode = 1;
+  };
+  if (opts.verify && opts.resetPassword) {
+    outputError({ message: "Provide only one of --verify or --reset-password" });
     return;
   }
   if (opts.verify && opts.printSql) {
-    console.error("\u2717 --verify cannot be combined with --print-sql");
-    process.exitCode = 1;
+    outputError({ message: "--verify cannot be combined with --print-sql" });
     return;
   }
   const shouldPrintSql = !!opts.printSql;
   const redactPasswords = (sql) => redactPasswordsInSql(sql);
+  const providerWarning = validateProvider(opts.provider);
+  if (providerWarning) {
+    console.warn(`\u26A0 ${providerWarning}`);
+  }
   if (!conn && !opts.dbUrl && !opts.host && !opts.port && !opts.username && !opts.adminPassword) {
     if (shouldPrintSql) {
       const database = (opts.dbname ?? process.env.PGDATABASE ?? "postgres").trim();
@@ -26775,12 +27959,14 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         database,
         monitoringUser: opts.monitoringUser,
         monitoringPassword: monPassword,
-        includeOptionalPermissions: includeOptionalPermissions2
+        includeOptionalPermissions: includeOptionalPermissions2,
+        provider: opts.provider
       });
       console.log(`
 --- SQL plan (offline; not connected) ---`);
       console.log(`-- database: ${database}`);
       console.log(`-- monitoring user: ${opts.monitoringUser}`);
+      console.log(`-- provider: ${opts.provider ?? "self-managed"}`);
       console.log(`-- optional permissions: ${includeOptionalPermissions2 ? "enabled" : "skipped"}`);
       for (const step of plan.steps) {
         console.log(`
@@ -26794,6 +27980,281 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       return;
     }
   }
+  if (opts.supabase) {
+    let supabaseConfig;
+    try {
+      let projectRef = opts.supabaseProjectRef;
+      if (!projectRef && conn) {
+        projectRef = extractProjectRefFromUrl(conn);
+      }
+      supabaseConfig = resolveSupabaseConfig({
+        accessToken: opts.supabaseAccessToken,
+        projectRef
+      });
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      outputError({ message: msg });
+      return;
+    }
+    const includeOptionalPermissions2 = !opts.skipOptionalPermissions;
+    if (!jsonOutput) {
+      console.log(`Supabase mode: project ref ${supabaseConfig.projectRef}`);
+      console.log(`Monitoring user: ${opts.monitoringUser}`);
+      console.log(`Optional permissions: ${includeOptionalPermissions2 ? "enabled" : "skipped"}`);
+    }
+    const supabaseClient = new SupabaseClient(supabaseConfig);
+    let databaseUrl = null;
+    if (jsonOutput) {
+      databaseUrl = await fetchPoolerDatabaseUrl(supabaseConfig, opts.monitoringUser);
+    }
+    try {
+      const database = await supabaseClient.getCurrentDatabase();
+      if (!database) {
+        throw new Error("Failed to resolve current database name");
+      }
+      if (!jsonOutput) {
+        console.log(`Database: ${database}`);
+      }
+      if (opts.verify) {
+        const v = await verifyInitSetupViaSupabase({
+          client: supabaseClient,
+          database,
+          monitoringUser: opts.monitoringUser,
+          includeOptionalPermissions: includeOptionalPermissions2
+        });
+        if (v.ok) {
+          if (jsonOutput) {
+            const result = {
+              success: true,
+              mode: "supabase",
+              action: "verify",
+              database,
+              monitoringUser: opts.monitoringUser,
+              verified: true,
+              missingOptional: v.missingOptional
+            };
+            if (databaseUrl) {
+              result.databaseUrl = databaseUrl;
+            }
+            outputJson(result);
+          } else {
+            console.log("\u2713 prepare-db verify: OK");
+            if (v.missingOptional.length > 0) {
+              console.log("\u26A0 Optional items missing:");
+              for (const m of v.missingOptional)
+                console.log(`- ${m}`);
+            }
+          }
+          return;
+        }
+        if (jsonOutput) {
+          const result = {
+            success: false,
+            mode: "supabase",
+            action: "verify",
+            database,
+            monitoringUser: opts.monitoringUser,
+            verified: false,
+            missingRequired: v.missingRequired,
+            missingOptional: v.missingOptional
+          };
+          if (databaseUrl) {
+            result.databaseUrl = databaseUrl;
+          }
+          outputJson(result);
+        } else {
+          console.error("\u2717 prepare-db verify failed: missing required items");
+          for (const m of v.missingRequired)
+            console.error(`- ${m}`);
+          if (v.missingOptional.length > 0) {
+            console.error("Optional items missing:");
+            for (const m of v.missingOptional)
+              console.error(`- ${m}`);
+          }
+        }
+        process.exitCode = 1;
+        return;
+      }
+      let monPassword;
+      let passwordGenerated = false;
+      try {
+        const resolved = await resolveMonitoringPassword({
+          passwordFlag: opts.password,
+          passwordEnv: process.env.PGAI_MON_PASSWORD,
+          monitoringUser: opts.monitoringUser
+        });
+        monPassword = resolved.password;
+        passwordGenerated = resolved.generated;
+        if (resolved.generated) {
+          const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
+          if (canPrint) {
+            if (!jsonOutput) {
+              const shellSafe = monPassword.replace(/'/g, "'\\''");
+              console.error("");
+              console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+              console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+              console.error("");
+              console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+            }
+          } else {
+            console.error([
+              `\u2717 Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
+              "",
+              "Provide it explicitly:",
+              "  --password <password>   or   PGAI_MON_PASSWORD=...",
+              "",
+              "Or (NOT recommended) print the generated password:",
+              "  --print-password"
+            ].join(`
+`));
+            process.exitCode = 1;
+            return;
+          }
+        }
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        outputError({ message: msg });
+        return;
+      }
+      const plan = await buildInitPlan({
+        database,
+        monitoringUser: opts.monitoringUser,
+        monitoringPassword: monPassword,
+        includeOptionalPermissions: includeOptionalPermissions2
+      });
+      const supabaseApplicableSteps = plan.steps.filter((s) => s.name !== "03.optional_rds" && s.name !== "04.optional_self_managed");
+      const effectivePlan = opts.resetPassword ? { ...plan, steps: supabaseApplicableSteps.filter((s) => s.name === "01.role") } : { ...plan, steps: supabaseApplicableSteps };
+      if (shouldPrintSql) {
+        console.log(`
+--- SQL plan ---`);
+        for (const step of effectivePlan.steps) {
+          console.log(`
+-- ${step.name}${step.optional ? " (optional)" : ""}`);
+          console.log(redactPasswords(step.sql));
+        }
+        console.log(`
+--- end SQL plan ---
+`);
+        console.log("Note: passwords are redacted in the printed SQL output.");
+        return;
+      }
+      const { applied, skippedOptional } = await applyInitPlanViaSupabase({
+        client: supabaseClient,
+        plan: effectivePlan
+      });
+      if (jsonOutput) {
+        const result = {
+          success: true,
+          mode: "supabase",
+          action: opts.resetPassword ? "reset-password" : "apply",
+          database,
+          monitoringUser: opts.monitoringUser,
+          applied,
+          skippedOptional,
+          warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+        };
+        if (passwordGenerated) {
+          result.generatedPassword = monPassword;
+        }
+        if (databaseUrl) {
+          result.databaseUrl = databaseUrl;
+        }
+        outputJson(result);
+      } else {
+        console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
+        if (skippedOptional.length > 0) {
+          console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
+          for (const s of skippedOptional)
+            console.log(`- ${s}`);
+        }
+        if (process.stdout.isTTY) {
+          console.log(`Applied ${applied.length} steps`);
+        }
+      }
+    } catch (error2) {
+      const errAny = error2;
+      let message = "";
+      if (error2 instanceof Error && error2.message) {
+        message = error2.message;
+      } else if (errAny && typeof errAny === "object" && typeof errAny.message === "string" && errAny.message) {
+        message = errAny.message;
+      } else {
+        message = String(error2);
+      }
+      if (!message || message === "[object Object]") {
+        message = "Unknown error";
+      }
+      const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
+      const failedStep = stepMatch?.[1];
+      const errorObj = { message };
+      if (failedStep)
+        errorObj.step = failedStep;
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code)
+          errorObj.code = errAny.code;
+        if (typeof errAny.detail === "string" && errAny.detail)
+          errorObj.detail = errAny.detail;
+        if (typeof errAny.hint === "string" && errAny.hint)
+          errorObj.hint = errAny.hint;
+        if (typeof errAny.httpStatus === "number")
+          errorObj.httpStatus = errAny.httpStatus;
+      }
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: "supabase",
+          error: errorObj
+        });
+        process.exitCode = 1;
+      } else {
+        console.error(`Error: prepare-db (Supabase): ${message}`);
+        if (failedStep) {
+          console.error(`  Step: ${failedStep}`);
+        }
+        if (errAny && typeof errAny === "object") {
+          if (typeof errAny.code === "string" && errAny.code) {
+            console.error(`  Code: ${errAny.code}`);
+          }
+          if (typeof errAny.detail === "string" && errAny.detail) {
+            console.error(`  Detail: ${errAny.detail}`);
+          }
+          if (typeof errAny.hint === "string" && errAny.hint) {
+            console.error(`  Hint: ${errAny.hint}`);
+          }
+          if (typeof errAny.httpStatus === "number") {
+            console.error(`  HTTP Status: ${errAny.httpStatus}`);
+          }
+        }
+        if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+          if (errAny.code === "42501") {
+            if (failedStep === "01.role") {
+              console.error("  Context: role creation/update requires CREATEROLE or superuser");
+            } else if (failedStep === "02.permissions") {
+              console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+            }
+            console.error("  Fix: ensure your Supabase access token has sufficient permissions");
+            console.error("  Tip: run with --print-sql to review the exact SQL plan");
+          }
+        }
+        if (errAny && typeof errAny === "object" && typeof errAny.httpStatus === "number") {
+          if (errAny.httpStatus === 401) {
+            console.error("  Hint: invalid or expired access token; generate a new one at https://supabase.com/dashboard/account/tokens");
+          }
+          if (errAny.httpStatus === 403) {
+            console.error("  Hint: access denied; check your token permissions and project access");
+          }
+          if (errAny.httpStatus === 404) {
+            console.error("  Hint: project not found; verify the project reference is correct");
+          }
+          if (errAny.httpStatus === 429) {
+            console.error("  Hint: rate limited; wait a moment and try again");
+          }
+        }
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
   let adminConn;
   try {
     adminConn = resolveAdminConnection({
@@ -26808,18 +28269,24 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
     });
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    console.error(`Error: prepare-db: ${msg}`);
-    if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
-      console.error("");
-      cmd.outputHelp({ error: true });
+    if (jsonOutput) {
+      outputError({ message: msg });
+    } else {
+      console.error(`Error: prepare-db: ${msg}`);
+      if (typeof msg === "string" && msg.startsWith("Connection is required.")) {
+        console.error("");
+        cmd.outputHelp({ error: true });
+      }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return;
   }
   const includeOptionalPermissions = !opts.skipOptionalPermissions;
-  console.log(`Connecting to: ${adminConn.display}`);
-  console.log(`Monitoring user: ${opts.monitoringUser}`);
-  console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+  if (!jsonOutput) {
+    console.log(`Connecting to: ${adminConn.display}`);
+    console.log(`Monitoring user: ${opts.monitoringUser}`);
+    console.log(`Optional permissions: ${includeOptionalPermissions ? "enabled" : "skipped"}`);
+  }
   let client;
   try {
     const connResult = await connectWithSslFallback(Client, adminConn);
@@ -26834,29 +28301,57 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         client,
         database,
         monitoringUser: opts.monitoringUser,
-        includeOptionalPermissions
+        includeOptionalPermissions,
+        provider: opts.provider
       });
       if (v.ok) {
-        console.log("\u2713 prepare-db verify: OK");
-        if (v.missingOptional.length > 0) {
-          console.log("\u26A0 Optional items missing:");
-          for (const m of v.missingOptional)
-            console.log(`- ${m}`);
+        if (jsonOutput) {
+          outputJson({
+            success: true,
+            mode: "direct",
+            action: "verify",
+            database,
+            monitoringUser: opts.monitoringUser,
+            provider: opts.provider,
+            verified: true,
+            missingOptional: v.missingOptional
+          });
+        } else {
+          console.log(`\u2713 prepare-db verify: OK${opts.provider ? ` (provider: ${opts.provider})` : ""}`);
+          if (v.missingOptional.length > 0) {
+            console.log("\u26A0 Optional items missing:");
+            for (const m of v.missingOptional)
+              console.log(`- ${m}`);
+          }
         }
         return;
       }
-      console.error("\u2717 prepare-db verify failed: missing required items");
-      for (const m of v.missingRequired)
-        console.error(`- ${m}`);
-      if (v.missingOptional.length > 0) {
-        console.error("Optional items missing:");
-        for (const m of v.missingOptional)
+      if (jsonOutput) {
+        outputJson({
+          success: false,
+          mode: "direct",
+          action: "verify",
+          database,
+          monitoringUser: opts.monitoringUser,
+          verified: false,
+          missingRequired: v.missingRequired,
+          missingOptional: v.missingOptional
+        });
+      } else {
+        console.error("\u2717 prepare-db verify failed: missing required items");
+        for (const m of v.missingRequired)
           console.error(`- ${m}`);
+        if (v.missingOptional.length > 0) {
+          console.error("Optional items missing:");
+          for (const m of v.missingOptional)
+            console.error(`- ${m}`);
+        }
       }
       process.exitCode = 1;
       return;
     }
     let monPassword;
+    let passwordGenerated = false;
     try {
       const resolved = await resolveMonitoringPassword({
         passwordFlag: opts.password,
@@ -26864,15 +28359,18 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
         monitoringUser: opts.monitoringUser
       });
       monPassword = resolved.password;
+      passwordGenerated = resolved.generated;
       if (resolved.generated) {
-        const canPrint = process.stdout.isTTY || !!opts.printPassword;
+        const canPrint = process.stdout.isTTY || !!opts.printPassword || jsonOutput;
         if (canPrint) {
-          const shellSafe = monPassword.replace(/'/g, "'\\''");
-          console.error("");
-          console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
-          console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
-          console.error("");
-          console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+          if (!jsonOutput) {
+            const shellSafe = monPassword.replace(/'/g, "'\\''");
+            console.error("");
+            console.error(`Generated monitoring password for ${opts.monitoringUser} (copy/paste):`);
+            console.error(`PGAI_MON_PASSWORD='${shellSafe}'`);
+            console.error("");
+            console.log("Store it securely (or rerun with --password / PGAI_MON_PASSWORD to set your own).");
+          }
         } else {
           console.error([
             `\u2717 Monitoring password was auto-generated for ${opts.monitoringUser} but not printed in non-interactive mode.`,
@@ -26890,17 +28388,22 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       }
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
-      console.error(`\u2717 ${msg}`);
-      process.exitCode = 1;
+      outputError({ message: msg });
       return;
     }
     const plan = await buildInitPlan({
       database,
       monitoringUser: opts.monitoringUser,
       monitoringPassword: monPassword,
-      includeOptionalPermissions
+      includeOptionalPermissions,
+      provider: opts.provider
     });
     const effectivePlan = opts.resetPassword ? { ...plan, steps: plan.steps.filter((s) => s.name === "01.role") } : plan;
+    if (opts.resetPassword && effectivePlan.steps.length === 0) {
+      console.error(`\u2717 --reset-password not supported for provider "${opts.provider}" (role creation is skipped)`);
+      process.exitCode = 1;
+      return;
+    }
     if (shouldPrintSql) {
       console.log(`
 --- SQL plan ---`);
@@ -26916,14 +28419,31 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
       return;
     }
     const { applied, skippedOptional } = await applyInitPlan({ client, plan: effectivePlan });
-    console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
-    if (skippedOptional.length > 0) {
-      console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
-      for (const s of skippedOptional)
-        console.log(`- ${s}`);
-    }
-    if (process.stdout.isTTY) {
-      console.log(`Applied ${applied.length} steps`);
+    if (jsonOutput) {
+      const result = {
+        success: true,
+        mode: "direct",
+        action: opts.resetPassword ? "reset-password" : "apply",
+        database,
+        monitoringUser: opts.monitoringUser,
+        applied,
+        skippedOptional,
+        warnings: skippedOptional.length > 0 ? ["Some optional steps were skipped (not supported or insufficient privileges)"] : []
+      };
+      if (passwordGenerated) {
+        result.generatedPassword = monPassword;
+      }
+      outputJson(result);
+    } else {
+      console.log(opts.resetPassword ? "\u2713 prepare-db password reset completed" : "\u2713 prepare-db completed");
+      if (skippedOptional.length > 0) {
+        console.log("\u26A0 Some optional steps were skipped (not supported or insufficient privileges):");
+        for (const s of skippedOptional)
+          console.log(`- ${s}`);
+      }
+      if (process.stdout.isTTY) {
+        console.log(`Applied ${applied.length} steps`);
+      }
     }
   } catch (error2) {
     const errAny = error2;
@@ -26938,45 +28458,65 @@ program2.command("prepare-db [conn]").description("prepare database for monitori
     if (!message || message === "[object Object]") {
       message = "Unknown error";
     }
-    console.error(`Error: prepare-db: ${message}`);
     const stepMatch = typeof message === "string" ? message.match(/Failed at step "([^"]+)":/i) : null;
     const failedStep = stepMatch?.[1];
-    if (failedStep) {
-      console.error(`  Step: ${failedStep}`);
-    }
+    const errorObj = { message };
+    if (failedStep)
+      errorObj.step = failedStep;
     if (errAny && typeof errAny === "object") {
-      if (typeof errAny.code === "string" && errAny.code) {
-        console.error(`  Code: ${errAny.code}`);
-      }
-      if (typeof errAny.detail === "string" && errAny.detail) {
-        console.error(`  Detail: ${errAny.detail}`);
-      }
-      if (typeof errAny.hint === "string" && errAny.hint) {
-        console.error(`  Hint: ${errAny.hint}`);
+      if (typeof errAny.code === "string" && errAny.code)
+        errorObj.code = errAny.code;
+      if (typeof errAny.detail === "string" && errAny.detail)
+        errorObj.detail = errAny.detail;
+      if (typeof errAny.hint === "string" && errAny.hint)
+        errorObj.hint = errAny.hint;
+    }
+    if (jsonOutput) {
+      outputJson({
+        success: false,
+        mode: "direct",
+        error: errorObj
+      });
+      process.exitCode = 1;
+    } else {
+      console.error(`Error: prepare-db: ${message}`);
+      if (failedStep) {
+        console.error(`  Step: ${failedStep}`);
       }
-    }
-    if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
-      if (errAny.code === "42501") {
-        if (failedStep === "01.role") {
-          console.error("  Context: role creation/update requires CREATEROLE or superuser");
-        } else if (failedStep === "02.permissions") {
-          console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+      if (errAny && typeof errAny === "object") {
+        if (typeof errAny.code === "string" && errAny.code) {
+          console.error(`  Code: ${errAny.code}`);
+        }
+        if (typeof errAny.detail === "string" && errAny.detail) {
+          console.error(`  Detail: ${errAny.detail}`);
+        }
+        if (typeof errAny.hint === "string" && errAny.hint) {
+          console.error(`  Hint: ${errAny.hint}`);
         }
-        console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
-        console.error("  Fix: on managed Postgres, use the provider's admin/master user");
-        console.error("  Tip: run with --print-sql to review the exact SQL plan");
-      }
-      if (errAny.code === "ECONNREFUSED") {
-        console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
-      }
-      if (errAny.code === "ENOTFOUND") {
-        console.error("  Hint: DNS resolution failed; double-check the host name");
       }
-      if (errAny.code === "ETIMEDOUT") {
-        console.error("  Hint: connection timed out; check network/firewall rules");
+      if (errAny && typeof errAny === "object" && typeof errAny.code === "string") {
+        if (errAny.code === "42501") {
+          if (failedStep === "01.role") {
+            console.error("  Context: role creation/update requires CREATEROLE or superuser");
+          } else if (failedStep === "02.permissions") {
+            console.error("  Context: grants/view/search_path require sufficient GRANT/DDL privileges");
+          }
+          console.error("  Fix: connect as a superuser (or a role with CREATEROLE and sufficient GRANT privileges)");
+          console.error("  Fix: on managed Postgres, use the provider's admin/master user");
+          console.error("  Tip: run with --print-sql to review the exact SQL plan");
+        }
+        if (errAny.code === "ECONNREFUSED") {
+          console.error("  Hint: check host/port and ensure Postgres is reachable from this machine");
+        }
+        if (errAny.code === "ENOTFOUND") {
+          console.error("  Hint: DNS resolution failed; double-check the host name");
+        }
+        if (errAny.code === "ETIMEDOUT") {
+          console.error("  Hint: connection timed out; check network/firewall rules");
+        }
       }
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
   } finally {
     if (client) {
       try {
@@ -27213,14 +28753,10 @@ mon.command("local-install").description("install local monitoring stack (genera
   console.log(`Project directory: ${projectDir}
 `);
   const envFile = path5.resolve(projectDir, ".env");
-  let existingTag = null;
   let existingRegistry = null;
   let existingPassword = null;
   if (fs5.existsSync(envFile)) {
     const existingEnv = fs5.readFileSync(envFile, "utf8");
-    const tagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
-    if (tagMatch)
-      existingTag = tagMatch[1].trim();
     const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
     if (registryMatch)
       existingRegistry = registryMatch[1].trim();
@@ -27228,7 +28764,7 @@ mon.command("local-install").description("install local monitoring stack (genera
     if (pwdMatch)
       existingPassword = pwdMatch[1].trim();
   }
-  const imageTag = opts.tag || process.env.PGAI_TAG || existingTag || package_default.version;
+  const imageTag = opts.tag || package_default.version;
   const envLines = [`PGAI_TAG=${imageTag}`];
   if (existingRegistry) {
     envLines.push(`PGAI_REGISTRY=${existingRegistry}`);
@@ -27565,6 +29101,9 @@ var MONITORING_CONTAINERS = [
   "sources-generator",
   "postgres-reports"
 ];
+var COMPOSE_PROJECT_NAME = "postgres_ai";
+var DOCKER_NETWORK_NAME = `${COMPOSE_PROJECT_NAME}_default`;
+var NETWORK_CLEANUP_DELAY_MS = 2000;
 async function removeOrphanedContainers() {
   for (const container of MONITORING_CONTAINERS) {
     try {
@@ -27573,7 +29112,18 @@ async function removeOrphanedContainers() {
   }
 }
 mon.command("stop").description("stop monitoring services").action(async () => {
-  const code = await runCompose(["down"]);
+  let code = await runCompose(["down", "--remove-orphans"]);
+  if (code !== 0) {
+    await removeOrphanedContainers();
+    await new Promise((resolve6) => setTimeout(resolve6, NETWORK_CLEANUP_DELAY_MS));
+    code = await runCompose(["down", "--remove-orphans"]);
+  }
+  if (code !== 0) {
+    try {
+      await execFilePromise("docker", ["network", "rm", DOCKER_NETWORK_NAME]);
+      code = 0;
+    } catch {}
+  }
   if (code !== 0)
     process.exitCode = code;
 });
@@ -28340,18 +29890,36 @@ function interpretEscapes2(str2) {
 `).replace(/\\t/g, "\t").replace(/\\r/g, "\r").replace(/\\"/g, '"').replace(/\\'/g, "'").replace(/\x00/g, "\\");
 }
 var issues = program2.command("issues").description("issues management");
-issues.command("list").description("list issues").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+issues.command("list").description("list issues").option("--status <status>", "filter by status: open, closed, or all (default: all)").option("--limit <n>", "max number of issues to return (default: 20)", parseInt).option("--offset <n>", "number of issues to skip (default: 0)", parseInt).option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (opts) => {
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issues...");
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
     const { apiKey } = getConfig(rootOpts);
     if (!apiKey) {
+      spinner.stop();
       console.error("API key is required. Run 'pgai auth' first or set --api-key.");
       process.exitCode = 1;
       return;
     }
+    const orgId = cfg.orgId ?? undefined;
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
-    const result = await fetchIssues2({ apiKey, apiBaseUrl, debug: !!opts.debug });
+    let statusFilter;
+    if (opts.status === "open") {
+      statusFilter = "open";
+    } else if (opts.status === "closed") {
+      statusFilter = "closed";
+    }
+    const result = await fetchIssues2({
+      apiKey,
+      apiBaseUrl,
+      orgId,
+      status: statusFilter,
+      limit: opts.limit,
+      offset: opts.offset,
+      debug: !!opts.debug
+    });
+    spinner.stop();
     const trimmed = Array.isArray(result) ? result.map((r) => ({
       id: r.id,
       title: r.title,
@@ -28360,17 +29928,20 @@ issues.command("list").description("list issues").option("--debug", "enable debu
     })) : result;
     printResult(trimmed, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;
   }
 });
 issues.command("view <issueId>").description("view issue details and comments").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (issueId, opts) => {
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching issue...");
   try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
     const { apiKey } = getConfig(rootOpts);
     if (!apiKey) {
+      spinner.stop();
       console.error("API key is required. Run 'pgai auth' first or set --api-key.");
       process.exitCode = 1;
       return;
@@ -28378,32 +29949,38 @@ issues.command("view <issueId>").description("view issue details and comments").
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
     const issue2 = await fetchIssue2({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
     if (!issue2) {
+      spinner.stop();
       console.error("Issue not found");
       process.exitCode = 1;
       return;
     }
+    spinner.update("Fetching comments...");
     const comments = await fetchIssueComments2({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+    spinner.stop();
     const combined = { issue: issue2, comments };
     printResult(combined, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;
   }
 });
 issues.command("post-comment <issueId> <content>").description("post a new comment to an issue").option("--parent <uuid>", "parent comment id").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (issueId, content, opts) => {
+  if (opts.debug) {
+    console.log(`Debug: Original content: ${JSON.stringify(content)}`);
+  }
+  content = interpretEscapes2(content);
+  if (opts.debug) {
+    console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+  }
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Posting comment...");
   try {
-    if (opts.debug) {
-      console.log(`Debug: Original content: ${JSON.stringify(content)}`);
-    }
-    content = interpretEscapes2(content);
-    if (opts.debug) {
-      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
-    }
     const rootOpts = program2.opts();
     const cfg = readConfig();
     const { apiKey } = getConfig(rootOpts);
     if (!apiKey) {
+      spinner.stop();
       console.error("API key is required. Run 'pgai auth' first or set --api-key.");
       process.exitCode = 1;
       return;
@@ -28417,41 +29994,44 @@ issues.command("post-comment <issueId> <content>").description("post a new comme
       parentCommentId: opts.parent,
       debug: !!opts.debug
     });
+    spinner.stop();
     printResult(result, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;
   }
 });
-issues.command("create <title>").description("create a new issue").option("--org-id <id>", "organization id (defaults to config orgId)", (v) => parseInt(v, 10)).option("--project-id <id>", "project id", (v) => parseInt(v, 10)).option("--description <text>", "issue description (supports \\\\n)").option("--label <label>", "issue label (repeatable)", (value, previous) => {
+issues.command("create <title>").description("create a new issue").option("--org-id <id>", "organization id (defaults to config orgId)", (v) => parseInt(v, 10)).option("--project-id <id>", "project id", (v) => parseInt(v, 10)).option("--description <text>", "issue description (use \\n for newlines)").option("--label <label>", "issue label (repeatable)", (value, previous) => {
   previous.push(value);
   return previous;
 }, []).option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (rawTitle, opts) => {
+  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 title = interpretEscapes2(String(rawTitle || "").trim());
+  if (!title) {
+    console.error("title is required");
+    process.exitCode = 1;
+    return;
+  }
+  const orgId = typeof opts.orgId === "number" && !Number.isNaN(opts.orgId) ? opts.orgId : cfg.orgId;
+  if (typeof orgId !== "number") {
+    console.error("org_id is required. Either pass --org-id or run 'pgai auth' to store it in config.");
+    process.exitCode = 1;
+    return;
+  }
+  const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
+  const labels = Array.isArray(opts.label) && opts.label.length > 0 ? opts.label.map(String) : undefined;
+  const projectId = typeof opts.projectId === "number" && !Number.isNaN(opts.projectId) ? opts.projectId : undefined;
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating issue...");
   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 title = interpretEscapes2(String(rawTitle || "").trim());
-    if (!title) {
-      console.error("title is required");
-      process.exitCode = 1;
-      return;
-    }
-    const orgId = typeof opts.orgId === "number" && !Number.isNaN(opts.orgId) ? opts.orgId : cfg.orgId;
-    if (typeof orgId !== "number") {
-      console.error("org_id is required. Either pass --org-id or run 'pgai auth' to store it in config.");
-      process.exitCode = 1;
-      return;
-    }
-    const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
-    const labels = Array.isArray(opts.label) && opts.label.length > 0 ? opts.label.map(String) : undefined;
-    const projectId = typeof opts.projectId === "number" && !Number.isNaN(opts.projectId) ? opts.projectId : undefined;
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
     const result = await createIssue2({
       apiKey,
@@ -28463,57 +30043,60 @@ issues.command("create <title>").description("create a new issue").option("--org
       labels,
       debug: !!opts.debug
     });
+    spinner.stop();
     printResult(result, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;
   }
 });
-issues.command("update <issueId>").description("update an existing issue (title/description/status/labels)").option("--title <text>", "new title (supports \\\\n)").option("--description <text>", "new description (supports \\\\n)").option("--status <value>", "status: open|closed|0|1").option("--label <label>", "set labels (repeatable). If provided, replaces existing labels.", (value, previous) => {
+issues.command("update <issueId>").description("update an existing issue (title/description/status/labels)").option("--title <text>", "new title (use \\n for newlines)").option("--description <text>", "new description (use \\n for newlines)").option("--status <value>", "status: open|closed|0|1").option("--label <label>", "set labels (repeatable). If provided, replaces existing labels.", (value, previous) => {
   previous.push(value);
   return previous;
 }, []).option("--clear-labels", "set labels to an empty list").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (issueId, 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 title = opts.title !== undefined ? interpretEscapes2(String(opts.title)) : undefined;
-    const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
-    let status = undefined;
-    if (opts.status !== undefined) {
-      const raw = String(opts.status).trim().toLowerCase();
-      if (raw === "open")
-        status = 0;
-      else if (raw === "closed")
-        status = 1;
-      else {
-        const n = Number(raw);
-        if (!Number.isFinite(n)) {
-          console.error("status must be open|closed|0|1");
-          process.exitCode = 1;
-          return;
-        }
-        status = n;
-      }
-      if (status !== 0 && status !== 1) {
-        console.error("status must be 0 (open) or 1 (closed)");
+  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 title = opts.title !== undefined ? interpretEscapes2(String(opts.title)) : undefined;
+  const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
+  let status = undefined;
+  if (opts.status !== undefined) {
+    const raw = String(opts.status).trim().toLowerCase();
+    if (raw === "open")
+      status = 0;
+    else if (raw === "closed")
+      status = 1;
+    else {
+      const n = Number(raw);
+      if (!Number.isFinite(n)) {
+        console.error("status must be open|closed|0|1");
         process.exitCode = 1;
         return;
       }
+      status = n;
     }
-    let labels = undefined;
-    if (opts.clearLabels) {
-      labels = [];
-    } else if (Array.isArray(opts.label) && opts.label.length > 0) {
-      labels = opts.label.map(String);
+    if (status !== 0 && status !== 1) {
+      console.error("status must be 0 (open) or 1 (closed)");
+      process.exitCode = 1;
+      return;
     }
+  }
+  let labels = undefined;
+  if (opts.clearLabels) {
+    labels = [];
+  } else if (Array.isArray(opts.label) && opts.label.length > 0) {
+    labels = opts.label.map(String);
+  }
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating issue...");
+  try {
     const result = await updateIssue2({
       apiKey,
       apiBaseUrl,
@@ -28524,40 +30107,217 @@ issues.command("update <issueId>").description("update an existing issue (title/
       labels,
       debug: !!opts.debug
     });
+    spinner.stop();
     printResult(result, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;
   }
 });
 issues.command("update-comment <commentId> <content>").description("update an existing issue comment").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (commentId, content, opts) => {
+  if (opts.debug) {
+    console.log(`Debug: Original content: ${JSON.stringify(content)}`);
+  }
+  content = interpretEscapes2(content);
+  if (opts.debug) {
+    console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+  }
+  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 spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating comment...");
   try {
-    if (opts.debug) {
-      console.log(`Debug: Original content: ${JSON.stringify(content)}`);
-    }
-    content = interpretEscapes2(content);
-    if (opts.debug) {
-      console.log(`Debug: Interpreted content: ${JSON.stringify(content)}`);
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const result = await updateIssueComment2({
+      apiKey,
+      apiBaseUrl,
+      commentId,
+      content,
+      debug: !!opts.debug
+    });
+    spinner.stop();
+    printResult(result, opts.json);
+  } catch (err) {
+    spinner.stop();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+issues.command("action-items <issueId>").description("list action items for an issue").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (issueId, opts) => {
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching action items...");
+  try {
+    const rootOpts = program2.opts();
+    const cfg = readConfig();
+    const { apiKey } = getConfig(rootOpts);
+    if (!apiKey) {
+      spinner.stop();
+      console.error("API key is required. Run 'pgai auth' first or set --api-key.");
+      process.exitCode = 1;
+      return;
     }
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const result = await fetchActionItems2({ apiKey, apiBaseUrl, issueId, debug: !!opts.debug });
+    spinner.stop();
+    printResult(result, opts.json);
+  } catch (err) {
+    spinner.stop();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+issues.command("view-action-item <actionItemIds...>").description("view action item(s) with all details (supports multiple IDs)").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (actionItemIds, opts) => {
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Fetching action item(s)...");
+  try {
     const rootOpts = program2.opts();
     const cfg = readConfig();
     const { apiKey } = getConfig(rootOpts);
     if (!apiKey) {
+      spinner.stop();
       console.error("API key is required. Run 'pgai auth' first or set --api-key.");
       process.exitCode = 1;
       return;
     }
     const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
-    const result = await updateIssueComment2({
+    const result = await fetchActionItem2({ apiKey, apiBaseUrl, actionItemIds, debug: !!opts.debug });
+    if (result.length === 0) {
+      spinner.stop();
+      console.error("Action item(s) not found");
+      process.exitCode = 1;
+      return;
+    }
+    spinner.stop();
+    printResult(result, opts.json);
+  } catch (err) {
+    spinner.stop();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+issues.command("create-action-item <issueId> <title>").description("create a new action item for an issue").option("--description <text>", "detailed description (use \\n for newlines)").option("--sql-action <sql>", "SQL command to execute").option("--config <json>", 'config change as JSON: {"parameter":"...","value":"..."} (repeatable)', (value, previous) => {
+  try {
+    previous.push(JSON.parse(value));
+  } catch {
+    console.error(`Invalid JSON for --config: ${value}`);
+    process.exit(1);
+  }
+  return previous;
+}, []).option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (issueId, rawTitle, opts) => {
+  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 title = interpretEscapes2(String(rawTitle || "").trim());
+  if (!title) {
+    console.error("title is required");
+    process.exitCode = 1;
+    return;
+  }
+  const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
+  const sqlAction = opts.sqlAction;
+  const configs = Array.isArray(opts.config) && opts.config.length > 0 ? opts.config : undefined;
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Creating action item...");
+  try {
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    const result = await createActionItem2({
       apiKey,
       apiBaseUrl,
-      commentId,
-      content,
+      issueId,
+      title,
+      description,
+      sqlAction,
+      configs,
       debug: !!opts.debug
     });
-    printResult(result, opts.json);
+    spinner.stop();
+    printResult({ id: result }, opts.json);
+  } catch (err) {
+    spinner.stop();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(message);
+    process.exitCode = 1;
+  }
+});
+issues.command("update-action-item <actionItemId>").description("update an action item (title, description, status, sql_action, configs)").option("--title <text>", "new title (use \\n for newlines)").option("--description <text>", "new description (use \\n for newlines)").option("--done", "mark as done").option("--not-done", "mark as not done").option("--status <value>", "status: waiting_for_approval|approved|rejected").option("--status-reason <text>", "reason for status change").option("--sql-action <sql>", "SQL command (use empty string to clear)").option("--config <json>", "config change as JSON (repeatable, replaces all configs)", (value, previous) => {
+  try {
+    previous.push(JSON.parse(value));
+  } catch {
+    console.error(`Invalid JSON for --config: ${value}`);
+    process.exit(1);
+  }
+  return previous;
+}, []).option("--clear-configs", "clear all config changes").option("--debug", "enable debug output").option("--json", "output raw JSON").action(async (actionItemId, opts) => {
+  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 title = opts.title !== undefined ? interpretEscapes2(String(opts.title)) : undefined;
+  const description = opts.description !== undefined ? interpretEscapes2(String(opts.description)) : undefined;
+  let isDone = undefined;
+  if (opts.done)
+    isDone = true;
+  else if (opts.notDone)
+    isDone = false;
+  let status = undefined;
+  if (opts.status !== undefined) {
+    const validStatuses = ["waiting_for_approval", "approved", "rejected"];
+    if (!validStatuses.includes(opts.status)) {
+      console.error(`status must be one of: ${validStatuses.join(", ")}`);
+      process.exitCode = 1;
+      return;
+    }
+    status = opts.status;
+  }
+  const statusReason = opts.statusReason;
+  const sqlAction = opts.sqlAction;
+  let configs = undefined;
+  if (opts.clearConfigs) {
+    configs = [];
+  } else if (Array.isArray(opts.config) && opts.config.length > 0) {
+    configs = opts.config;
+  }
+  if (title === undefined && description === undefined && isDone === undefined && status === undefined && statusReason === undefined && sqlAction === undefined && configs === undefined) {
+    console.error("At least one update option is required");
+    process.exitCode = 1;
+    return;
+  }
+  const spinner = createTtySpinner(process.stdout.isTTY ?? false, "Updating action item...");
+  try {
+    const { apiBaseUrl } = resolveBaseUrls2(rootOpts, cfg);
+    await updateActionItem2({
+      apiKey,
+      apiBaseUrl,
+      actionItemId,
+      title,
+      description,
+      isDone,
+      status,
+      statusReason,
+      sqlAction,
+      configs,
+      debug: !!opts.debug
+    });
+    spinner.stop();
+    printResult({ success: true }, opts.json);
   } catch (err) {
+    spinner.stop();
     const message = err instanceof Error ? err.message : String(err);
     console.error(message);
     process.exitCode = 1;