openmates 0.11.0-alpha.6 → 0.11.0-alpha.8

package/dist/{chunk-NU4XR6MF.js → chunk-2YHQ7NP4.js}

@@ -1,3 +1,7 @@
+import {
+  uploadFile
+} from "./chunk-SFTCIVE2.js";
+
 // src/client.ts
 import { randomUUID } from "crypto";
 import { platform as platform2, release } from "os";
@@ -180,12 +184,29 @@ var OpenMatesHttpClient = class {
   async post(path, body, headers = {}) {
     return this.request("POST", path, body, headers);
   }
-  async delete(path, headers = {}) {
-    return this.request("DELETE", path, void 0, headers);
+  async delete(path, body, headers = {}) {
+    return this.request("DELETE", path, body, headers);
   }
   async patch(path, body, headers = {}) {
     return this.request("PATCH", path, body, headers);
   }
+  async getBinary(path, headers = {}) {
+    const url = `${this.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const requestHeaders = {
+      Accept: "application/pdf,application/octet-stream",
+      ...headers
+    };
+    const cookieHeader = this.formatCookieHeader();
+    if (cookieHeader) requestHeaders.Cookie = cookieHeader;
+    const response = await fetch(url, { method: "GET", headers: requestHeaders });
+    this.captureCookies(response);
+    return {
+      ok: response.ok,
+      status: response.status,
+      data: new Uint8Array(await response.arrayBuffer()),
+      headers: response.headers
+    };
+  }
   async request(method, path, body, headers = {}) {
     const url = `${this.apiUrl}${path.startsWith("/") ? path : `/${path}`}`;
     const requestHeaders = {
@@ -603,18 +624,6 @@ function buildSession(onDisk, masterKey) {
     autoLogoutMinutes: onDisk.autoLogoutMinutes
   };
 }
-function loadIncognitoHistory() {
-  const filePath = join(ensureStateDir(), "incognito.json");
-  return readJsonFile(filePath) ?? [];
-}
-function saveIncognitoHistory(items) {
-  const filePath = join(ensureStateDir(), "incognito.json");
-  writeJsonFile(filePath, items);
-}
-function clearIncognitoHistory() {
-  const filePath = join(ensureStateDir(), "incognito.json");
-  writeJsonFile(filePath, []);
-}
 var SYNC_CACHE_FILE = "sync_cache.json";
 function saveSyncCache(cache) {
   const filePath = join(ensureStateDir(), SYNC_CACHE_FILE);
@@ -1718,7 +1727,11 @@ var BLOCKED_SETTINGS_MUTATE_PATHS = /* @__PURE__ */ new Set([
   "/v1/auth/setup_password",
   "/v1/auth/2fa/setup/initiate",
   "/v1/auth/2fa/setup/provider",
-  "/v1/auth/2fa/setup/verify-signup"
+  "/v1/auth/2fa/setup/verify-signup",
+  "/v1/settings/delete-account",
+  "/v1/settings/request-action-verification",
+  "/v1/settings/verify-action-code",
+  "/v1/settings/user/disable-2fa"
 ]);
 var OpenMatesClient = class _OpenMatesClient {
   apiUrl;
@@ -1834,7 +1847,6 @@ var OpenMatesClient = class _OpenMatesClient {
       await this.http.post("/v1/auth/logout", {}, this.getCliRequestHeaders()).catch(() => void 0);
     }
     clearSession();
-    clearIncognitoHistory();
   }
   // -------------------------------------------------------------------------
   // Chats
@@ -2375,12 +2387,6 @@ var OpenMatesClient = class _OpenMatesClient {
     let followUpSuggestions = [];
     const streamOpts = { onStream: params.onStream };
     if (params.incognito) {
-      const history = loadIncognitoHistory();
-      history.push({
-        role: "user",
-        content: params.message,
-        createdAt: Date.now()
-      });
       try {
         const resp = await ws.collectAiResponse(messageId, chatId, streamOpts);
         assistant = resp.content;
@@ -2389,12 +2395,6 @@ var OpenMatesClient = class _OpenMatesClient {
       } finally {
         ws.close();
       }
-      history.push({
-        role: "assistant",
-        content: assistant,
-        createdAt: Date.now()
-      });
-      saveIncognitoHistory(history);
     } else {
       try {
         const resp = await ws.collectAiResponse(messageId, chatId, streamOpts);
@@ -2416,12 +2416,6 @@ var OpenMatesClient = class _OpenMatesClient {
       followUpSuggestions
     };
   }
-  getIncognitoHistory() {
-    return loadIncognitoHistory();
-  }
-  clearIncognitoHistory() {
-    clearIncognitoHistory();
-  }
   /**
    * Delete a chat by ID.
    *
@@ -2734,7 +2728,7 @@ var OpenMatesClient = class _OpenMatesClient {
     }
     return response.data;
   }
-  async settingsDelete(path) {
+  async settingsDelete(path, body) {
     this.requireSession();
     const normalizedPath = this.normalizePath(path);
     if (BLOCKED_SETTINGS_MUTATE_PATHS.has(normalizedPath)) {
@@ -2742,6 +2736,7 @@ var OpenMatesClient = class _OpenMatesClient {
     }
     const response = await this.http.delete(
       normalizedPath,
+      body,
       this.getCliRequestHeaders()
     );
     if (!response.ok) {
@@ -2793,6 +2788,123 @@ var OpenMatesClient = class _OpenMatesClient {
     }
     return response.data;
   }
+  async listInvoices() {
+    this.requireSession();
+    const response = await this.http.get(
+      "/v1/payments/invoices",
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch invoices (HTTP ${response.status})`);
+    }
+    return { invoices: response.data.invoices ?? [] };
+  }
+  async downloadInvoice(invoiceId) {
+    return this.downloadPaymentPdf(
+      `/v1/payments/invoices/${encodeURIComponent(invoiceId)}/download`,
+      `Invoice_${invoiceId}.pdf`
+    );
+  }
+  async downloadCreditNote(invoiceId) {
+    return this.downloadPaymentPdf(
+      `/v1/payments/invoices/${encodeURIComponent(invoiceId)}/credit-note/download`,
+      `CreditNote_${invoiceId}.pdf`
+    );
+  }
+  async requestRefund(invoiceId, emailEncryptionKey) {
+    this.requireSession();
+    const response = await this.http.post(
+      "/v1/payments/refund",
+      { invoice_id: invoiceId, email_encryption_key: emailEncryptionKey },
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Refund request failed (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async updateUsername(username) {
+    return this.settingsPost("user/username", { username });
+  }
+  async updateProfileImage(filePath) {
+    const { uploadProfileImage } = await import("./uploadService-3CAJXU4L.js");
+    const result = await uploadProfileImage(filePath, this.requireSession());
+    if (result.status === "rejected") {
+      throw new Error(result.detail ?? "Profile image rejected by content safety checks.");
+    }
+    if (result.status === "account_deleted") {
+      throw new Error("Account deleted due to repeated profile image policy violations.");
+    }
+    if (result.status !== "ok") {
+      throw new Error(result.detail ?? `Profile image upload failed with status '${result.status}'.`);
+    }
+    return result;
+  }
+  async getNewsletterCategories() {
+    this.requireSession();
+    const response = await this.http.get(
+      "/v1/newsletter/categories",
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch newsletter categories (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async updateNewsletterCategories(categories) {
+    this.requireSession();
+    const response = await this.http.patch(
+      "/v1/newsletter/categories",
+      { categories },
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to update newsletter categories (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async subscribeNewsletter(email, language = "en", darkmode = false) {
+    const response = await this.http.post(
+      "/v1/newsletter/subscribe",
+      { email, language, darkmode },
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Newsletter subscribe failed (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async confirmNewsletter(token) {
+    const response = await this.http.get(
+      `/v1/newsletter/confirm/${encodeURIComponent(token)}`,
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Newsletter confirmation failed (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async unsubscribeNewsletter(token) {
+    const response = await this.http.get(
+      `/v1/newsletter/unsubscribe/${encodeURIComponent(token)}`,
+      this.getCliRequestHeaders()
+    );
+    if (!response.ok) {
+      throw new Error(`Newsletter unsubscribe failed (HTTP ${response.status})`);
+    }
+    return response.data;
+  }
+  async updateEmailNotificationSettings(payload) {
+    const { ws } = await this.openWsClient();
+    try {
+      const ackPromise = ws.waitForMessage("email_notification_settings_ack");
+      ws.send("email_notification_settings", payload);
+      const ack = await ackPromise;
+      return ack.payload;
+    } finally {
+      ws.close();
+    }
+  }
   // -------------------------------------------------------------------------
   // Daily Inspirations
   // -------------------------------------------------------------------------
@@ -3257,6 +3369,17 @@ Required: ${schema.required.join(", ")}`
     if (path.startsWith("/")) return path;
     return `/v1/settings/${path}`;
   }
+  async downloadPaymentPdf(path, fallbackFilename) {
+    this.requireSession();
+    const response = await this.http.getBinary(path, this.getCliRequestHeaders());
+    if (!response.ok) {
+      throw new Error(`Download failed (HTTP ${response.status})`);
+    }
+    return {
+      filename: filenameFromContentDisposition(response.headers.get("content-disposition")) ?? fallbackFilename,
+      data: response.data
+    };
+  }
   requireSession() {
     if (!this.session) {
       throw new Error("Not logged in. Run `openmates login`.");
@@ -3632,6 +3755,15 @@ function parseNewChatSuggestionText(text) {
   const skillId = raw.slice(dashIdx + 1);
   return { body, appId, skillId };
 }
+function filenameFromContentDisposition(header2) {
+  if (!header2) return null;
+  const encoded = /filename\*=UTF-8''([^;]+)/i.exec(header2)?.[1];
+  if (encoded) return decodeURIComponent(encoded);
+  const quoted = /filename="([^"]+)"/i.exec(header2)?.[1];
+  if (quoted) return quoted;
+  const plain = /filename=([^;]+)/i.exec(header2)?.[1];
+  return plain?.trim() ?? null;
+}
 function sleep(ms) {
   return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
@@ -3921,8 +4053,8 @@ var SecretRegistry = class {
     const sortedResults = [];
     for (const result of results) {
       const endIdx = result[0];
-      const matches = result[1];
-      for (const match of matches) {
+      const matches2 = result[1];
+      for (const match of matches2) {
         sortedResults.push({ endIndex: endIdx, match });
       }
     }
@@ -4845,97 +4977,6 @@ function formatEmbedsForMessage(embeds) {
   return "\n" + embeds.map((e) => e.referenceBlock).join("\n");
 }
 
-// src/uploadService.ts
-import { readFileSync as readFileSync4 } from "fs";
-import { basename as basename2 } from "path";
-var UPLOAD_MAX_ATTEMPTS = 3;
-var UPLOAD_RETRY_DELAY_MS = 2e3;
-function getUploadUrl(apiUrl) {
-  try {
-    const url = new URL(apiUrl);
-    if (url.hostname === "localhost") return "http://localhost:8001";
-  } catch {
-  }
-  return "https://upload.openmates.org";
-}
-function getUploadOrigin(apiUrl) {
-  try {
-    const url = new URL(apiUrl);
-    if (url.hostname === "localhost") return "http://localhost:5173";
-    if (url.hostname.startsWith("api.")) {
-      return `${url.protocol}//app.${url.hostname.slice(4)}`;
-    }
-  } catch {
-  }
-  return "https://app.openmates.org";
-}
-async function uploadFile(filePath, session) {
-  const filename = basename2(filePath);
-  const fileBytes = readFileSync4(filePath);
-  const uploadUrl = `${getUploadUrl(session.apiUrl)}/v1/upload/file`;
-  const origin = getUploadOrigin(session.apiUrl);
-  const cookies = [];
-  if (session.cookies?.auth_refresh_token) {
-    cookies.push(`auth_refresh_token=${session.cookies.auth_refresh_token}`);
-  }
-  let response;
-  let lastError;
-  for (let attempt = 1; attempt <= UPLOAD_MAX_ATTEMPTS; attempt++) {
-    try {
-      const blob = new Blob([fileBytes]);
-      const formData = new FormData();
-      formData.append("file", blob, filename);
-      response = await fetch(uploadUrl, {
-        method: "POST",
-        body: formData,
-        headers: {
-          Origin: origin,
-          ...cookies.length > 0 ? { Cookie: cookies.join("; ") } : {}
-        },
-        signal: AbortSignal.timeout(10 * 60 * 1e3)
-        // 10-minute timeout
-      });
-      break;
-    } catch (error) {
-      lastError = error;
-      if (attempt === UPLOAD_MAX_ATTEMPTS) break;
-      await new Promise((resolve4) => setTimeout(resolve4, UPLOAD_RETRY_DELAY_MS));
-    }
-  }
-  if (!response) {
-    const message = lastError instanceof Error ? lastError.message : String(lastError);
-    throw new Error(message || "Upload request failed.");
-  }
-  if (!response.ok) {
-    const status = response.status;
-    let errorMessage;
-    switch (status) {
-      case 401:
-        errorMessage = "Authentication failed. Run `openmates login` to re-authenticate.";
-        break;
-      case 413:
-        errorMessage = "File too large (maximum 100 MB).";
-        break;
-      case 415:
-        errorMessage = "Unsupported file type.";
-        break;
-      case 422: {
-        const body = await response.text().catch(() => "");
-        errorMessage = body.includes("malware") ? "File rejected: malware detected." : body.includes("content_safety") ? "File rejected: content safety violation." : `Upload validation failed: ${body}`;
-        break;
-      }
-      case 429:
-        errorMessage = "Upload rate limit exceeded. Try again in a minute.";
-        break;
-      default:
-        errorMessage = `Upload failed (HTTP ${status}).`;
-    }
-    throw new Error(errorMessage);
-  }
-  const data = await response.json();
-  return data;
-}
-
 // src/embedRenderers.ts
 var str = (v) => typeof v === "string" && v.length > 0 ? v : null;
 var DIRECT_TYPES = /* @__PURE__ */ new Set([
@@ -5985,13 +6026,13 @@ function formatTs(ts) {
 
 // src/server.ts
 import { execSync, spawn as nodeSpawn } from "child_process";
-import { copyFileSync, existsSync as existsSync5, readFileSync as readFileSync6, rmSync as rmSync3 } from "fs";
+import { copyFileSync, existsSync as existsSync5, readFileSync as readFileSync5, rmSync as rmSync3 } from "fs";
 import { createInterface as createInterface2 } from "readline";
 import { homedir as homedir5 } from "os";
 import { join as join3, resolve as resolve3 } from "path";
 
 // src/serverConfig.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync5, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { homedir as homedir4 } from "os";
 import { join as join2, resolve as resolve2 } from "path";
 var STATE_DIR = join2(homedir4(), ".openmates");
@@ -6012,7 +6053,7 @@ function loadServerConfig() {
   const filePath = join2(STATE_DIR, CONFIG_FILE);
   if (!existsSync4(filePath)) return null;
   try {
-    return JSON.parse(readFileSync5(filePath, "utf-8"));
+    return JSON.parse(readFileSync4(filePath, "utf-8"));
   } catch {
     return null;
   }
@@ -6090,7 +6131,7 @@ function requireGit() {
 }
 function hasLlmCredentials(envPath) {
   if (!existsSync5(envPath)) return false;
-  const content = readFileSync6(envPath, "utf-8");
+  const content = readFileSync5(envPath, "utf-8");
   for (const line of content.split("\n")) {
     const trimmed = line.trim();
     if (trimmed.startsWith("#") || !trimmed) continue;
@@ -6821,17 +6862,11 @@ Run 'openmates chats show ` + chatId + "' to check if suggestions have been save
     return;
   }
   if (subcommand === "incognito-history") {
-    const history = client.getIncognitoHistory();
-    if (flags.json === true) {
-      printJson2(history);
-    } else {
-      printIncognitoHistory(history);
-    }
+    printIncognitoNoHistoryNotice(flags.json === true);
     return;
   }
   if (subcommand === "incognito-clear") {
-    client.clearIncognitoHistory();
-    console.log("Incognito history cleared.");
+    printIncognitoNoHistoryNotice(flags.json === true);
     return;
   }
   if (subcommand === "show") {
@@ -7699,125 +7734,652 @@ async function handleEmbeds(client, subcommand, rest, flags) {
   printEmbedsHelp();
   process.exit(1);
 }
-async function handleSettings(client, subcommand, rest, flags) {
-  if (!subcommand || subcommand === "help" || flags.help === true) {
-    printSettingsHelp(client);
+var SETTINGS_EXECUTABLE_COMMANDS = [
+  { path: ["account", "info"], description: "Show account info", examples: ["openmates settings account info --json"] },
+  { path: ["account", "timezone", "set"], description: "Set account timezone", examples: ["openmates settings account timezone set Europe/Berlin"] },
+  { path: ["account", "export", "manifest"], description: "Show account export manifest", examples: ["openmates settings account export manifest --json"] },
+  { path: ["account", "export", "data"], description: "Fetch account export data", examples: ["openmates settings account export data --json"] },
+  { path: ["account", "import-chat"], description: "Import a CLI chat export file", examples: ["openmates settings account import-chat ./chat.yml", "openmates settings account import-chat ./payload.json"] },
+  { path: ["account", "username", "set"], description: "Change account username", examples: ["openmates settings account username set alice_123"] },
+  { path: ["account", "profile-picture", "set"], description: "Upload a profile picture", examples: ["openmates settings account profile-picture set ./avatar.jpg"] },
+  { path: ["account", "chats", "stats"], description: "Show chat statistics", examples: ["openmates settings account chats stats"] },
+  { path: ["account", "delete", "preview"], description: "Preview account deletion impact", examples: ["openmates settings account delete preview"] },
+  { path: ["account", "storage", "overview"], description: "Show storage overview", examples: ["openmates settings account storage overview"] },
+  { path: ["account", "storage", "files"], description: "List stored files", examples: ["openmates settings account storage files --category images"] },
+  { path: ["account", "storage", "delete"], description: "Delete one stored file by file ID", examples: ["openmates settings account storage delete <file-id> --yes"] },
+  { path: ["interface", "language", "set"], description: "Set interface language", examples: ["openmates settings interface language set en"] },
+  { path: ["interface", "dark-mode", "set"], description: "Set dark mode on or off", examples: ["openmates settings interface dark-mode set on"] },
+  { path: ["interface", "font", "set"], description: "Set interface font", examples: ["openmates settings interface font set lexend"] },
+  { path: ["ai", "models", "set-defaults"], description: "Set default AI models", examples: ["openmates settings ai models set-defaults --simple gpt-5.4 --complex claude-opus-4-7"] },
+  { path: ["privacy", "auto-delete", "chats", "set"], description: "Set chat auto-deletion period", examples: ["openmates settings privacy auto-delete chats set 90d"] },
+  { path: ["privacy", "debug-logs", "share"], description: "Create a debug log sharing session", examples: ["openmates settings privacy debug-logs share --duration 1h --confirm"] },
+  { path: ["billing", "overview"], description: "Show billing overview", examples: ["openmates settings billing overview"] },
+  { path: ["billing", "usage"], description: "Show usage history", examples: ["openmates settings billing usage --json"] },
+  { path: ["billing", "usage", "summaries"], description: "Show usage summaries", examples: ["openmates settings billing usage summaries"] },
+  { path: ["billing", "usage", "daily"], description: "Show daily usage overview", examples: ["openmates settings billing usage daily"] },
+  { path: ["billing", "usage", "export"], description: "Export usage data", examples: ["openmates settings billing usage export --json"] },
+  { path: ["billing", "invoices", "list"], description: "List invoices", examples: ["openmates settings billing invoices list --json"] },
+  { path: ["billing", "invoices", "download"], description: "Download an invoice PDF", examples: ["openmates settings billing invoices download <invoice-id> --output ./invoices"] },
+  { path: ["billing", "invoices", "credit-note"], description: "Download a credit note PDF", examples: ["openmates settings billing invoices credit-note <invoice-id> --output ./invoices"] },
+  { path: ["billing", "invoices", "refund"], description: "Request a refund for an invoice", examples: ["openmates settings billing invoices refund <invoice-id> --email-encryption-key <base64>"] },
+  { path: ["billing", "gift-card", "redeem"], description: "Redeem a gift card", examples: ["openmates settings billing gift-card redeem ABCD-1234"] },
+  { path: ["billing", "gift-card", "list"], description: "List redeemed gift cards", examples: ["openmates settings billing gift-card list"] },
+  { path: ["billing", "auto-topup", "low-balance", "set"], description: "Configure low-balance auto top-up", examples: ["openmates settings billing auto-topup low-balance set --enabled true --amount 1000 --currency eur --email you@example.com"] },
+  { path: ["notifications", "status"], description: "Show notification settings", examples: ["openmates settings notifications status --json"] },
+  { path: ["notifications", "email", "set"], description: "Configure email notifications", examples: ["openmates settings notifications email set --enabled true --email you@example.com --ai-responses true --backup-reminder true --webhook-chats true"] },
+  { path: ["notifications", "backup", "set"], description: "Configure backup reminder emails", examples: ["openmates settings notifications backup set --enabled true --interval 30 --email you@example.com"] },
+  { path: ["reminders", "list"], description: "List active reminders", examples: ["openmates settings reminders list"] },
+  { path: ["reminders", "update"], description: "Update a reminder", examples: ["openmates settings reminders update <id> --enabled false"] },
+  { path: ["reminders", "delete"], description: "Delete a reminder", examples: ["openmates settings reminders delete <id> --yes"] },
+  { path: ["developers", "api-keys", "list"], description: "List API keys", examples: ["openmates settings developers api-keys list"] },
+  { path: ["developers", "api-keys", "revoke"], description: "Revoke an API key", examples: ["openmates settings developers api-keys revoke <key-id> --yes"] },
+  { path: ["report-issue", "create"], description: "Report an issue", examples: ['openmates settings report-issue create --title "Bug" --body "What happened"'] },
+  { path: ["report-issue", "status"], description: "Show issue status", examples: ["openmates settings report-issue status <issue-id>"] },
+  { path: ["mates", "list"], description: "List available mates", examples: ["openmates settings mates list"] },
+  { path: ["mates", "info"], description: "Show mate details", examples: ["openmates settings mates info software_development"] },
+  { path: ["mates", "consent"], description: "Record mate settings consent", examples: ["openmates settings mates consent --yes"] },
+  { path: ["newsletter", "categories"], description: "Show newsletter category preferences", examples: ["openmates settings newsletter categories"] },
+  { path: ["newsletter", "categories", "set"], description: "Set newsletter category preferences", examples: ["openmates settings newsletter categories set --updates true --tips true --daily false"] },
+  { path: ["newsletter", "subscribe"], description: "Subscribe an email to the newsletter", examples: ["openmates settings newsletter subscribe you@example.com --language en"] },
+  { path: ["newsletter", "confirm"], description: "Confirm newsletter subscription token", examples: ["openmates settings newsletter confirm <token>"] },
+  { path: ["newsletter", "unsubscribe"], description: "Unsubscribe with newsletter token", examples: ["openmates settings newsletter unsubscribe <token>"] },
+  { path: ["memories"], description: "Manage encrypted memories", examples: ["openmates settings memories list", `openmates settings memories create --app-id code --item-type projects --data '{"name":"OpenMates"}'`] }
+];
+var SETTINGS_INFO_COMMANDS = [
+  { path: ["account", "email"], description: "Email changes are web-only", webPath: "account/email", reason: "Email changes require a guided identity verification flow.", examples: ["openmates settings account email"] },
+  { path: ["account", "delete"], description: "Account deletion is web-only", webPath: "account/delete", reason: "Account deletion requires browser-based reauthentication and explicit confirmation.", examples: ["openmates settings account delete"] },
+  { path: ["security"], description: "Security settings are web-only", webPath: "account/security", reason: "Security settings require browser APIs or high-risk reauthentication.", examples: ["openmates settings security"] },
+  { path: ["security", "passkeys"], description: "Passkeys are web-only", webPath: "account/security/passkeys", reason: "Passkeys require WebAuthn browser APIs.", examples: ["openmates settings security passkeys"] },
+  { path: ["security", "password"], description: "Password changes are web-only", webPath: "account/security/password", reason: "The CLI never asks for account credentials.", examples: ["openmates settings security password"] },
+  { path: ["security", "2fa"], description: "2FA setup and changes are web-only", webPath: "account/security/2fa", reason: "2FA setup requires a guided browser verification flow.", examples: ["openmates settings security 2fa"] },
+  { path: ["security", "recovery-key"], description: "Recovery key settings are web-only", webPath: "account/security/recovery-key", reason: "Recovery keys are a high-risk account recovery surface.", examples: ["openmates settings security recovery-key"] },
+  { path: ["security", "sessions"], description: "Session management is web-only", webPath: "account/security/sessions", reason: "The CLI is a paired restricted session; approval and revocation stay in the browser.", examples: ["openmates settings security sessions"] },
+  { path: ["billing", "buy-credits"], description: "Credit purchase is web-only", webPath: "billing/buy-credits", reason: "Payment checkout must use the browser/payment provider UI.", examples: ["openmates settings billing buy-credits"] },
+  { path: ["billing", "gift-card", "buy"], description: "Gift card purchase is web-only", webPath: "billing/gift-cards/buy", reason: "Payment checkout must use the browser/payment provider UI.", examples: ["openmates settings billing gift-card buy"] },
+  { path: ["billing", "auto-topup", "monthly"], description: "Monthly auto top-up is web-only for now", webPath: "billing/auto-topup/monthly", reason: "Recurring payment setup needs a payment-flow audit before CLI support.", examples: ["openmates settings billing auto-topup monthly"] },
+  { path: ["privacy", "personal-data"], description: "Personal data management is not CLI-ready yet", webPath: "privacy/hide-personal-data", reason: "The CLI needs a dedicated encrypted personal-data UX before exposing writes.", examples: ["openmates settings privacy personal-data"] },
+  { path: ["shared", "tip"], description: "Tips are web-only", webPath: "shared/tip", reason: "Payment checkout must use the browser/payment provider UI.", examples: ["openmates settings shared tip"] },
+  { path: ["developers", "api-keys", "create"], description: "API key creation is web-only", webPath: "developers/api-keys", reason: "API key secrets are shown once and need the browser approval flow.", examples: ["openmates settings developers api-keys create"] },
+  { path: ["developers", "devices"], description: "Developer devices are web-only", webPath: "developers/devices", reason: "Device approvals and revocations are sensitive.", examples: ["openmates settings developers devices"] },
+  { path: ["developers", "webhooks"], description: "Developer webhooks are not CLI-ready yet", webPath: "developers/webhooks", reason: "Webhook CRUD needs a backend/API audit before CLI support.", examples: ["openmates settings developers webhooks"] },
+  { path: ["support"], description: "Support payments are web-only", webPath: "support", reason: "Payment flows must use the browser/payment provider UI.", examples: ["openmates settings support"] },
+  { path: ["incognito", "info"], description: "Explain incognito mode", reason: "Incognito chats are sent without saving chat history. The CLI stores no incognito transcript.", examples: ['openmates chats incognito "Private question"'] },
+  { path: ["server"], description: "Server admin settings are web/admin-only", webPath: "server", reason: "Use `openmates server --help` for self-hosted terminal server management.", examples: ["openmates server status"] }
+];
+function matches(actual, expected) {
+  return expected.every((part, index) => actual[index] === part);
+}
+function findSettingsInfoCommand(tokens) {
+  const all = [...SETTINGS_INFO_COMMANDS, ...SETTINGS_EXECUTABLE_COMMANDS];
+  return all.sort((a, b) => b.path.length - a.path.length).find((command) => matches(tokens, command.path)) ?? null;
+}
+async function printSettingsResult(resultPromise, flags) {
+  const result = await resultPromise;
+  flags.json === true ? printJson2(result) : printGenericObject(result);
+}
+async function printSettingsMutationResult(resultPromise, flags) {
+  const result = await resultPromise;
+  if (flags.json === true) {
+    printJson2(result);
     return;
   }
-  if (subcommand === "get") {
-    const path = rest[0];
-    if (!path) {
-      console.error("Missing path.\n");
-      printSettingsHelp();
-      process.exit(1);
+  process.stdout.write("\x1B[32m\u2713\x1B[0m Settings updated\n");
+  if (result && typeof result === "object") printGenericObject(result);
+}
+function addQueryParam(params, key, value) {
+  if (typeof value === "string" && value.length > 0) params.set(key, value);
+}
+function parseOnOff(value, label) {
+  if (value === "on" || value === "true" || value === "1") return true;
+  if (value === "off" || value === "false" || value === "0") return false;
+  throw new Error(`Invalid ${label} value '${value ?? ""}'. Use on/off or true/false.`);
+}
+function parseRequiredNumber(value, flag) {
+  if (typeof value !== "string") throw new Error(`Missing ${flag}.`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`Invalid ${flag}: ${value}`);
+  return parsed;
+}
+function parseOptionalBoolean(value, fallback, label) {
+  if (value === void 0) return fallback;
+  if (typeof value === "boolean") return value;
+  return parseOnOff(value, label);
+}
+function parseDataOrFlags(flags, booleanFlags) {
+  if (typeof flags.data === "string") return JSON.parse(flags.data);
+  const body = {};
+  for (const key of booleanFlags) {
+    if (flags[key] !== void 0) body[key] = parseOnOff(String(flags[key]), key);
+  }
+  if (Object.keys(body).length === 0) throw new Error("Provide --data '<json>' or a supported flag.");
+  return body;
+}
+function parseChatImportPayload(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) throw new Error("Import file is empty.");
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) return { chats: parsed };
+    if (parsed && typeof parsed === "object" && Array.isArray(parsed.chats)) {
+      return parsed;
+    }
+    if (parsed && typeof parsed === "object") {
+      const object = parsed;
+      if (object.chat || object.messages) return { chats: [normalizeImportedChat(object)] };
+    }
+    throw new Error("JSON import must contain a chats array, a chat object, or messages.");
+  }
+  return { chats: [parseCliExportYaml(trimmed)] };
+}
+function normalizeImportedChat(source) {
+  const chat = source.chat && typeof source.chat === "object" ? source.chat : source;
+  const messages = Array.isArray(source.messages) ? source.messages : [];
+  return {
+    title: chat.title ?? null,
+    draft: chat.draft ?? null,
+    summary: chat.summary ?? null,
+    messages: messages.map((message) => normalizeImportedMessage(message))
+  };
+}
+function normalizeImportedMessage(message) {
+  return {
+    role: message.role,
+    content: message.content,
+    completed_at: message.completed_at ?? message.timestamp ?? null,
+    assistant_category: message.assistant_category ?? null,
+    thinking: message.thinking ?? null,
+    has_thinking: message.has_thinking ?? null,
+    thinking_tokens: message.thinking_tokens ?? null
+  };
+}
+function parseCliExportYaml(raw) {
+  const chat = {};
+  const messages = [];
+  const lines = raw.split("\n");
+  let section = null;
+  let currentMessage = null;
+  const multilineState = { current: null };
+  const setValue = (target, key, value, indent) => {
+    if (value === "|") {
+      target[key] = "";
+      multilineState.current = { target, key, indent: indent + 2 };
+      return;
     }
-    const result = await client.settingsGet(path);
-    if (flags.json === true) {
-      printJson2(result);
-    } else {
-      printGenericObject(result);
+    target[key] = parseYamlScalar(value);
+  };
+  for (const line of lines) {
+    const indent = line.match(/^ */)?.[0].length ?? 0;
+    const trimmed = line.trimEnd();
+    if (!trimmed.trim()) continue;
+    if (multilineState.current) {
+      if (indent >= multilineState.current.indent) {
+        const previous = String(multilineState.current.target[multilineState.current.key] ?? "");
+        const nextLine = line.slice(multilineState.current.indent);
+        multilineState.current.target[multilineState.current.key] = previous ? `${previous}
+${nextLine}` : nextLine;
+        continue;
+      }
+      multilineState.current = null;
     }
-    return;
-  }
-  if (subcommand === "post") {
-    const path = rest[0];
-    if (!path) {
-      console.error("Missing path.\n");
-      printSettingsHelp();
-      process.exit(1);
+    if (trimmed === "chat:") {
+      section = "chat";
+      currentMessage = null;
+      continue;
     }
-    const dataRaw = typeof flags.data === "string" ? flags.data : "{}";
-    const data = JSON.parse(dataRaw);
-    const result = await client.settingsPost(path, data);
-    if (flags.json === true) {
-      printJson2(result);
-    } else {
-      printGenericObject(result);
+    if (trimmed === "messages:") {
+      section = "messages";
+      currentMessage = null;
+      continue;
+    }
+    if (section === "messages" && trimmed.trim() === "-") {
+      currentMessage = {};
+      messages.push(currentMessage);
+      continue;
     }
+    const match = /^\s*([\w-]+):\s*(.*)$/.exec(line);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (section === "chat") setValue(chat, key, value, indent);
+    if (section === "messages" && currentMessage) setValue(currentMessage, key, value, indent);
+  }
+  if (messages.length === 0) throw new Error("Import YAML did not contain any messages.");
+  return normalizeImportedChat({ chat, messages });
+}
+function parseYamlScalar(value) {
+  const trimmed = value.trim();
+  if (trimmed === "null") return null;
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed !== "" && Number.isFinite(Number(trimmed))) return Number(trimmed);
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+  }
+  return trimmed;
+}
+async function saveDownloadedDocument(document, output) {
+  const { mkdir, writeFile } = await import("fs/promises");
+  const { join: join4, basename: basename2, dirname } = await import("path");
+  const target = typeof output === "string" ? output : ".";
+  const filename = basename2(document.filename || "document.pdf");
+  const filePath = target.endsWith(".pdf") ? target : join4(target, filename);
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, document.data);
+  return filePath;
+}
+function printMates(json) {
+  const mates = Object.entries(MATE_NAMES).map(([id, name]) => ({ id, name, mention: `@mate:${id}` }));
+  if (json) {
+    printJson2(mates);
     return;
   }
-  if (subcommand === "delete") {
-    const path = rest[0];
-    if (!path) {
-      console.error("Missing path.\n");
-      printSettingsHelp();
-      process.exit(1);
-    }
-    const result = await client.settingsDelete(path);
-    if (flags.json === true) {
-      printJson2(result);
-    } else {
-      printGenericObject(result);
-    }
+  header("Mates");
+  for (const mate of mates) console.log(`${mate.id.padEnd(28)} ${mate.name.padEnd(10)} ${mate.mention}`);
+}
+function printMateInfo(mateId, json) {
+  const name = MATE_NAMES[mateId];
+  if (!name) throw new Error(`Unknown mate '${mateId}'. Run 'openmates settings mates list'.`);
+  const data = { id: mateId, name, mention: `@mate:${mateId}` };
+  if (json) {
+    printJson2(data);
     return;
   }
-  if (subcommand === "patch") {
-    const path = rest[0];
-    if (!path) {
-      console.error("Missing path.\n");
-      printSettingsHelp();
-      process.exit(1);
+  header(`${name} (${mateId})`);
+  console.log(`Mention: ${data.mention}`);
+  console.log(`Use: openmates chats send "${data.mention} <message>"`);
+}
+async function confirmOrExit(question) {
+  const rl = await import("readline");
+  const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise((resolve4) => iface.question(question, resolve4));
+  iface.close();
+  if (answer.trim().toLowerCase() !== "y") {
+    console.log("Aborted.");
+    process.exit(0);
+  }
+}
+function printSettingsInfoCommand(client, command, json) {
+  const appUrl = deriveAppUrl(client.apiUrl);
+  const webUrl = command.webPath ? `${appUrl}/#settings/${command.webPath}` : null;
+  if (json) {
+    printJson2({
+      command: `openmates settings ${command.path.join(" ")}`,
+      supported_in_cli: false,
+      description: command.description,
+      reason: command.reason ?? null,
+      web_url: webUrl,
+      examples: command.examples
+    });
+    return;
+  }
+  header(command.description);
+  if (command.reason) console.log(command.reason);
+  if (webUrl) console.log(`
+Open in web app:
+  ${webUrl}`);
+  if (command.examples.length > 0) {
+    console.log("\nExamples:");
+    for (const example of command.examples) console.log(`  ${example}`);
+  }
+}
+async function handleSettings(client, subcommand, rest, flags) {
+  if (!subcommand || subcommand === "help") {
+    printSettingsHelp(client, subcommand ? [] : void 0);
+    return;
+  }
+  const tokens = [subcommand, ...rest].filter((token) => token !== "help");
+  if (rest.includes("help") || Boolean(flags.help)) {
+    printSettingsHelp(client, tokens);
+    return;
+  }
+  if (["get", "post", "patch", "delete"].includes(subcommand)) {
+    console.error(
+      "Raw settings passthrough is no longer supported. Use a predefined settings command.\n"
+    );
+    printSettingsHelp(client);
+    process.exit(1);
+  }
+  if (matches(tokens, ["account", "info"])) {
+    const user = await client.whoAmI();
+    flags.json === true ? printJson2(user) : printWhoAmI(user);
+    return;
+  }
+  if (matches(tokens, ["account", "timezone", "set"])) {
+    const timezone = rest[2];
+    if (!timezone) throw new Error("Missing timezone. Example: openmates settings account timezone set Europe/Berlin");
+    await printSettingsMutationResult(
+      client.settingsPost("user/timezone", { timezone }),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["account", "export", "manifest"])) {
+    await printSettingsResult(client.settingsGet("export-account-manifest"), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "export", "data"])) {
+    await printSettingsResult(client.settingsGet("export-account-data"), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "import-chat"])) {
+    const file = rest[1];
+    if (!file) throw new Error("Missing import file. Example: openmates settings account import-chat ./chat.yml");
+    const { readFile } = await import("fs/promises");
+    const content = await readFile(file, "utf-8");
+    await printSettingsMutationResult(
+      client.settingsPost("import-chat", parseChatImportPayload(content)),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["account", "username", "set"])) {
+    const username = rest[2];
+    if (!username) throw new Error("Missing username. Example: openmates settings account username set alice_123");
+    await printSettingsMutationResult(client.updateUsername(username), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "profile-picture", "set"])) {
+    const file = rest[2];
+    if (!file) throw new Error("Missing image file. Example: openmates settings account profile-picture set ./avatar.jpg");
+    await printSettingsMutationResult(client.updateProfileImage(file), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "chats", "stats"])) {
+    await printSettingsResult(client.settingsGet("chats"), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "delete", "preview"])) {
+    await printSettingsResult(client.settingsGet("delete-account-preview"), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "storage", "overview"])) {
+    await printSettingsResult(client.settingsGet("storage"), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "storage", "files"])) {
+    const params = new URLSearchParams();
+    addQueryParam(params, "category", flags.category ?? flags.type);
+    const query = params.toString();
+    await printSettingsResult(client.settingsGet(`storage/files${query ? `?${query}` : ""}`), flags);
+    return;
+  }
+  if (matches(tokens, ["account", "storage", "delete"])) {
+    const fileId = rest[3];
+    const category = typeof flags.category === "string" ? flags.category : void 0;
+    const scope = flags.all === true ? "all" : category ? "category" : "single";
+    if (scope === "single" && !fileId) throw new Error("Missing file ID.");
+    if (flags.yes !== true) await confirmOrExit(`Delete stored file data (${scope})? This cannot be undone. [y/N] `);
+    await printSettingsMutationResult(
+      client.settingsDelete("storage/files", { scope, file_id: fileId, category }),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["interface", "language", "set"])) {
+    const language = rest[2];
+    if (!language) throw new Error("Missing language code. Example: openmates settings interface language set en");
+    await printSettingsMutationResult(client.settingsPost("user/language", { language }), flags);
+    return;
+  }
+  if (matches(tokens, ["interface", "dark-mode", "set"])) {
+    const value = parseOnOff(rest[2], "dark mode");
+    await printSettingsMutationResult(client.settingsPost("user/darkmode", { dark_mode: value }), flags);
+    return;
+  }
+  if (matches(tokens, ["interface", "font", "set"])) {
+    const font = rest[2];
+    if (!font) throw new Error("Missing font. Example: openmates settings interface font set lexend");
+    await printSettingsMutationResult(client.settingsPost("user/ui-font", { ui_font: font }), flags);
+    return;
+  }
+  if (matches(tokens, ["ai", "models", "set-defaults"])) {
+    const simple = typeof flags.simple === "string" ? flags.simple : void 0;
+    const complex = typeof flags.complex === "string" ? flags.complex : void 0;
+    if (!simple && !complex) throw new Error("Provide --simple <model-id> and/or --complex <model-id>.");
+    await printSettingsMutationResult(client.settingsPost("ai-model-defaults", { simple, complex }), flags);
+    return;
+  }
+  if (matches(tokens, ["privacy", "auto-delete", "chats", "set"])) {
+    const period = rest[3];
+    if (!period) throw new Error("Missing period. Example: openmates settings privacy auto-delete chats set 90d");
+    await printSettingsMutationResult(client.settingsPost("auto-delete-chats", { period }), flags);
+    return;
+  }
+  if (matches(tokens, ["privacy", "debug-logs", "share"])) {
+    if (flags.yes !== true && flags.confirm !== true) {
+      await confirmOrExit("Share debug logs with OpenMates support? [y/N] ");
     }
-    const dataRaw = typeof flags.data === "string" ? flags.data : "{}";
-    const data = JSON.parse(dataRaw);
-    const result = await client.settingsPatch(path, data);
+    const duration = typeof flags.duration === "string" ? flags.duration : "1h";
+    await printSettingsMutationResult(client.settingsPost("debug-session", { duration }), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "overview"])) {
+    await printSettingsResult(client.settingsGet("billing"), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "usage", "summaries"])) {
+    await printSettingsResult(client.settingsGet("usage/summaries"), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "usage", "daily"])) {
+    await printSettingsResult(client.settingsGet("usage/daily-overview"), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "usage", "export"])) {
+    await printSettingsResult(client.settingsGet("usage/export"), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "usage"])) {
+    await printSettingsResult(client.settingsGet("usage"), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "invoices", "list"])) {
+    await printSettingsResult(client.listInvoices(), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "invoices", "download"])) {
+    const invoiceId = rest[2];
+    if (!invoiceId) throw new Error("Missing invoice ID.");
+    const document = await client.downloadInvoice(invoiceId);
+    const filePath = await saveDownloadedDocument(document, flags.output);
+    if (flags.json === true) printJson2({ path: filePath, filename: document.filename });
+    else console.log(`\x1B[32m\u2713\x1B[0m Invoice saved to ${filePath}`);
+    return;
+  }
+  if (matches(tokens, ["billing", "invoices", "credit-note"])) {
+    const invoiceId = rest[2];
+    if (!invoiceId) throw new Error("Missing invoice ID.");
+    const document = await client.downloadCreditNote(invoiceId);
+    const filePath = await saveDownloadedDocument(document, flags.output);
+    if (flags.json === true) printJson2({ path: filePath, filename: document.filename });
+    else console.log(`\x1B[32m\u2713\x1B[0m Credit note saved to ${filePath}`);
+    return;
+  }
+  if (matches(tokens, ["billing", "invoices", "refund"])) {
+    const invoiceId = rest[2];
+    const emailEncryptionKey = typeof flags["email-encryption-key"] === "string" ? flags["email-encryption-key"] : void 0;
+    if (!invoiceId) throw new Error("Missing invoice ID.");
+    if (!emailEncryptionKey) throw new Error("Missing --email-encryption-key. The backend requires the encrypted email key for refund requests.");
+    if (flags.yes !== true) await confirmOrExit(`Request refund for invoice ${invoiceId}? [y/N] `);
+    await printSettingsMutationResult(client.requestRefund(invoiceId, emailEncryptionKey), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "gift-card", "redeem"]) || subcommand === "gift-card" && rest[0] === "redeem") {
+    const code = matches(tokens, ["billing", "gift-card", "redeem"]) ? rest[2] : rest[1];
+    if (!code) throw new Error("Missing gift card code.");
+    const result = await client.redeemGiftCard(code);
     if (flags.json === true) {
       printJson2(result);
+    } else if (result.success) {
+      process.stdout.write(`\x1B[32m\u2713\x1B[0m Gift card redeemed! +${result.credits_added} credits
+`);
+      process.stdout.write(`  Balance: ${result.current_credits} credits
+`);
     } else {
-      printGenericObject(result);
+      process.stdout.write(`\x1B[31m\u2717\x1B[0m ${result.message}
+`);
     }
     return;
   }
+  if (matches(tokens, ["billing", "gift-card", "list"]) || subcommand === "gift-card" && rest[0] === "list") {
+    await printSettingsResult(client.listRedeemedGiftCards(), flags);
+    return;
+  }
+  if (matches(tokens, ["billing", "auto-topup", "low-balance", "set"])) {
+    const enabled = parseOnOff(String(flags.enabled ?? ""), "low-balance auto top-up");
+    const amount = parseRequiredNumber(flags.amount, "--amount");
+    const currency = typeof flags.currency === "string" ? flags.currency : "eur";
+    const email = typeof flags.email === "string" ? flags.email : void 0;
+    if (enabled && !email) throw new Error("Provide --email when enabling low-balance auto top-up.");
+    await printSettingsMutationResult(
+      client.settingsPost("auto-topup/low-balance", { enabled, threshold: 100, amount, currency, email }),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["notifications", "status"])) {
+    const user = await client.whoAmI();
+    const status = {
+      enabled: user.email_notifications_enabled ?? false,
+      preferences: user.email_notification_preferences ?? {},
+      backup_reminder_interval_days: user.backup_reminder_interval_days ?? null,
+      encrypted_notification_email_configured: Boolean(user.encrypted_notification_email)
+    };
+    flags.json === true ? printJson2(status) : printGenericObject(status);
+    return;
+  }
+  if (matches(tokens, ["notifications", "email", "set"])) {
+    const enabled = parseOnOff(String(flags.enabled ?? ""), "email notifications");
+    const email = typeof flags.email === "string" ? flags.email : null;
+    if (enabled && !email) throw new Error("Provide --email when enabling email notifications.");
+    const preferences = {
+      aiResponses: parseOptionalBoolean(flags["ai-responses"], true, "AI response notifications"),
+      backupReminder: parseOptionalBoolean(flags["backup-reminder"], false, "backup reminder notifications"),
+      webhookChats: parseOptionalBoolean(flags["webhook-chats"], false, "webhook chat notifications")
+    };
+    await printSettingsMutationResult(
+      client.updateEmailNotificationSettings({ enabled, email, preferences }),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["notifications", "backup", "set"])) {
+    const enabled = parseOnOff(String(flags.enabled ?? ""), "backup reminders");
+    const email = typeof flags.email === "string" ? flags.email : null;
+    const interval = parseRequiredNumber(flags.interval, "--interval");
+    if (enabled && !email) throw new Error("Provide --email when enabling backup reminders.");
+    await printSettingsMutationResult(
+      client.updateEmailNotificationSettings({
+        enabled,
+        email,
+        preferences: { aiResponses: false, backupReminder: enabled },
+        backup_reminder_interval_days: interval
+      }),
+      flags
+    );
+    return;
+  }
+  if (matches(tokens, ["reminders", "list"])) {
+    await printSettingsResult(client.settingsGet("reminders"), flags);
+    return;
+  }
+  if (matches(tokens, ["reminders", "update"])) {
+    const id = rest[1];
+    if (!id) throw new Error("Missing reminder ID.");
+    const body = parseDataOrFlags(flags, ["enabled"]);
+    await printSettingsMutationResult(client.settingsPatch(`reminders/${id}`, body), flags);
+    return;
+  }
+  if (matches(tokens, ["reminders", "delete"])) {
+    const id = rest[1];
+    if (!id) throw new Error("Missing reminder ID.");
+    if (flags.yes !== true) await confirmOrExit(`Delete reminder ${id}? [y/N] `);
+    await printSettingsMutationResult(client.settingsDelete(`reminders/${id}`), flags);
+    return;
+  }
+  if (matches(tokens, ["developers", "api-keys", "list"])) {
+    await printSettingsResult(client.settingsGet("api-keys"), flags);
+    return;
+  }
+  if (matches(tokens, ["developers", "api-keys", "revoke"])) {
+    const id = rest[2];
+    if (!id) throw new Error("Missing API key ID.");
+    if (flags.yes !== true) await confirmOrExit(`Revoke API key ${id}? [y/N] `);
+    await printSettingsMutationResult(client.settingsDelete(`api-keys/${id}`), flags);
+    return;
+  }
+  if (matches(tokens, ["report-issue", "create"])) {
+    const title = typeof flags.title === "string" ? flags.title : void 0;
+    const body = typeof flags.body === "string" ? flags.body : void 0;
+    if (!title || !body) throw new Error("Provide --title and --body.");
+    await printSettingsMutationResult(client.settingsPost("issues", { title, description: body }), flags);
+    return;
+  }
+  if (matches(tokens, ["report-issue", "status"])) {
+    const id = rest[1];
+    if (!id) throw new Error("Missing issue ID.");
+    await printSettingsResult(client.settingsGet(`issues/${id}/status`), flags);
+    return;
+  }
+  if (matches(tokens, ["mates", "list"])) {
+    printMates(flags.json === true);
+    return;
+  }
+  if (matches(tokens, ["mates", "info"])) {
+    const mateId = rest[1];
+    if (!mateId) throw new Error("Missing mate ID. Example: openmates settings mates info software_development");
+    printMateInfo(mateId, flags.json === true);
+    return;
+  }
+  if (matches(tokens, ["mates", "consent"])) {
+    if (flags.yes !== true) await confirmOrExit("Record consent for mate settings? [y/N] ");
+    await printSettingsMutationResult(client.settingsPost("user/consent/mates", { consent: true }), flags);
+    return;
+  }
+  if (matches(tokens, ["newsletter", "categories"]) && tokens.length === 2) {
+    await printSettingsResult(client.getNewsletterCategories(), flags);
+    return;
+  }
+  if (matches(tokens, ["newsletter", "categories", "set"])) {
+    const categories = {
+      updates_and_announcements: parseOptionalBoolean(flags.updates, true, "updates newsletter"),
+      tips_and_tricks: parseOptionalBoolean(flags.tips, true, "tips newsletter"),
+      daily_inspirations: parseOptionalBoolean(flags.daily, true, "daily inspirations newsletter")
+    };
+    await printSettingsMutationResult(client.updateNewsletterCategories(categories), flags);
+    return;
+  }
+  if (matches(tokens, ["newsletter", "subscribe"])) {
+    const email = rest[1];
+    if (!email) throw new Error("Missing email. Example: openmates settings newsletter subscribe you@example.com");
+    const language = typeof flags.language === "string" ? flags.language : "en";
+    const darkmode = parseOptionalBoolean(flags.darkmode, false, "newsletter dark mode");
+    await printSettingsMutationResult(client.subscribeNewsletter(email, language, darkmode), flags);
+    return;
+  }
+  if (matches(tokens, ["newsletter", "confirm"])) {
+    const token = rest[1];
+    if (!token) throw new Error("Missing confirmation token.");
+    await printSettingsMutationResult(client.confirmNewsletter(token), flags);
+    return;
+  }
+  if (matches(tokens, ["newsletter", "unsubscribe"])) {
+    const token = rest[1];
+    if (!token) throw new Error("Missing unsubscribe token.");
+    await printSettingsMutationResult(client.unsubscribeNewsletter(token), flags);
+    return;
+  }
   if (subcommand === "memories") {
     await handleMemories(client, rest, flags);
     return;
   }
-  if (subcommand === "gift-card") {
-    const action = rest[0];
-    if (action === "redeem") {
-      const code = rest[1];
-      if (!code) {
-        console.error("Missing gift card code.\n");
-        console.log("Usage: openmates settings gift-card redeem <CODE>");
-        process.exit(1);
-      }
-      const result = await client.redeemGiftCard(code);
-      if (flags.json === true) {
-        printJson2(result);
-      } else {
-        if (result.success) {
-          process.stdout.write(
-            `\x1B[32m\u2713\x1B[0m Gift card redeemed! +${result.credits_added} credits
-`
-          );
-          process.stdout.write(
-            `  Balance: ${result.current_credits} credits
-`
-          );
-        } else {
-          process.stdout.write(`\x1B[31m\u2717\x1B[0m ${result.message}
-`);
-        }
-      }
-      return;
-    }
-    if (action === "list") {
-      const result = await client.listRedeemedGiftCards();
-      if (flags.json === true) {
-        printJson2(result);
-      } else {
-        printGenericObject(result);
-      }
-      return;
-    }
-    console.log(`Gift card commands:
-  openmates settings gift-card redeem <CODE>    Redeem a gift card
-  openmates settings gift-card list             List redeemed gift cards`);
+  const webOnly = findSettingsInfoCommand(tokens);
+  if (webOnly) {
+    printSettingsInfoCommand(client, webOnly, flags.json === true);
     return;
   }
-  console.error(`Unknown settings subcommand '${subcommand}'.
+  console.error(`Unknown settings command '${tokens.join(" ")}'.
 `);
-  printSettingsHelp();
+  printSettingsHelp(client, [subcommand]);
   process.exit(1);
 }
 async function handleMemories(client, rest, flags) {
@@ -8370,21 +8932,13 @@ async function sendMessageStreaming(client, params, redactor) {
   }
   return result;
 }
-function printIncognitoHistory(history) {
-  if (history.length === 0) {
-    console.log("No incognito history.");
+function printIncognitoNoHistoryNotice(json) {
+  const message = "Incognito chats are not stored. There is no incognito history to show or clear.";
+  if (json) {
+    printJson2({ history: [], stored: false, message });
     return;
   }
-  header(`Incognito history  (${history.length} messages)`);
-  console.log();
-  for (const msg of history) {
-    const ts = formatTimestamp(Math.floor(msg.createdAt / 1e3));
-    const roleLabel = msg.role === "user" ? "\x1B[1mYou\x1B[0m" : "\x1B[36mAssistant\x1B[0m";
-    process.stdout.write(`${roleLabel}  \x1B[2m${ts}\x1B[0m
-`);
-    console.log(msg.content);
-    console.log();
-  }
+  console.log(message);
 }
 var SEP = `\x1B[2m${"\u2500".repeat(60)}\x1B[0m`;
 function parseMessageSegments(content) {
@@ -9351,23 +9905,23 @@ async function handleMentions(client, subcommand, _rest, flags) {
     const context = await client.buildMentionContext();
     const allOptions = listMentionOptions(context);
     const normalizedQuery = query.toLowerCase().replace(/[\s_-]+/g, "");
-    const matches = allOptions.filter((opt) => {
+    const matches2 = allOptions.filter((opt) => {
       const normalizedName = opt.displayName.toLowerCase().replace(/[@\s_-]+/g, "");
       const normalizedDesc = opt.description.toLowerCase().replace(/[\s_-]+/g, "");
       return normalizedName.includes(normalizedQuery) || normalizedDesc.includes(normalizedQuery);
     }).slice(0, 15);
     if (flags.json === true) {
-      console.log(JSON.stringify(matches, null, 2));
+      console.log(JSON.stringify(matches2, null, 2));
       return;
     }
-    if (matches.length === 0) {
+    if (matches2.length === 0) {
       console.log(`No mentions matching '${query}'.`);
       return;
     }
     process.stdout.write(`
 \x1B[1mMatches for '${query}':\x1B[0m
 `);
-    for (const m of matches) {
+    for (const m of matches2) {
       const typeLabel = m.type.replace("_", " ");
       process.stdout.write(
         `  \x1B[36m${m.displayName.padEnd(35)}\x1B[0m \x1B[2m${m.description} (${typeLabel})\x1B[0m
@@ -9512,7 +10066,7 @@ Commands:
   openmates apps [--help]                    App skill commands (list, run, ...)
   openmates mentions [--help]                List available @mentions
   openmates embeds [--help]                  Embed commands (show)
-  openmates settings [--help]                Memories
+  openmates settings [--help]                Predefined settings commands
   openmates inspirations [--lang <code>] [--json]   Daily inspirations
   openmates newchatsuggestions [--limit <n>] [--json]   Personalized new chat suggestions
   openmates server [--help]                   Server management (install, start, stop, ...)
@@ -9537,8 +10091,8 @@ function printChatsHelp() {
   openmates chats delete <id1> [id2] [id3] ... [--yes]
   openmates chats share [<chat-id>] [--expires <seconds>] [--password <pwd>] [--json]
   openmates chats incognito <message> [--json]
-  openmates chats incognito-history [--json]
-  openmates chats incognito-clear
+  openmates chats incognito-history [--json]      Deprecated: incognito stores no history
+  openmates chats incognito-clear                 Deprecated: incognito stores no history
 
 Options for 'list':
   --limit <n>   Number of chats per page (default: 10)
@@ -9662,72 +10216,33 @@ Examples:
   openmates inspirations --lang de
   openmates inspirations --json`);
 }
-function printSettingsHelp(client) {
+function printSettingsHelp(client, filter) {
+  const commands = [...SETTINGS_EXECUTABLE_COMMANDS, ...SETTINGS_INFO_COMMANDS].filter((command) => {
+    if (!filter || filter.length === 0) return true;
+    return filter.every((part, index) => command.path[index] === part);
+  }).sort((a, b) => a.path.join(" ").localeCompare(b.path.join(" ")));
   const appUrl = client ? deriveAppUrl(client.apiUrl) : "https://openmates.org";
-  const s = (path) => `${appUrl}/#settings/${path}`;
-  const h = (title) => `
-  \x1B[1m${title}\x1B[0m`;
-  console.log(`\x1B[1mSettings\x1B[0m
-${h("Account")}
-    openmates settings post user/username --data '{"encrypted_username":"..."}'
-    openmates settings post user/timezone --data '{"timezone":"Europe/Berlin"}'
-    openmates settings get export-account-manifest      GDPR data export manifest
-    openmates settings get export-account-data          GDPR data export
-    openmates settings post import-chat --data '<json>' Import a chat
-    openmates settings get storage [--json]             Storage overview
-    openmates settings get chats [--json]               Chat statistics
-    openmates settings get delete-account-preview       Preview account deletion
-    \x1B[2mSecurity (passkeys, password, 2FA, sessions): ${s("account/security")}\x1B[0m
-    \x1B[2mDelete account: ${s("account/delete")}\x1B[0m
-${h("Billing")}
-    openmates settings get billing [--json]             Balance & billing overview
-    openmates settings post auto-topup/low-balance --data '{"enabled":true,"amount":1000,"currency":"eur"}'
-    openmates settings get usage [--json]               Full usage history
-    openmates settings get usage/summaries [--json]     Usage summaries by type
-    openmates settings get usage/daily-overview [--json]
-    openmates settings get usage/export [--json]        Export usage as CSV
-    openmates settings gift-card redeem <CODE>          Redeem a gift card
-    openmates settings gift-card list                   List redeemed gift cards
-    \x1B[2mBuy credits: ${s("billing/buy-credits")}\x1B[0m
-    \x1B[2mMonthly auto top-up: ${s("billing/auto-topup/monthly")}\x1B[0m
-    \x1B[2mInvoices: ${s("billing/invoices")}\x1B[0m
-    \x1B[2mGift cards (buy/manage): ${s("billing/gift-cards")}\x1B[0m
-${h("Privacy")}
-    openmates settings post auto-delete-chats --data '{"period":"90d"}'
-    \x1B[2mHide personal data / anonymization: ${s("privacy/hide-personal-data")}\x1B[0m
-${h("Notifications")}
-    openmates settings get reminders [--json]           Active reminders
-    \x1B[2mChat notifications: ${s("notifications/chat")}\x1B[0m
-    \x1B[2mBackup reminders: ${s("notifications/backup")}\x1B[0m
-${h("Interface")}
-    openmates settings post user/language --data '{"language":"en"}'
-    openmates settings post user/darkmode --data '{"dark_mode":true}'
-    openmates settings post ai-model-defaults --data '{"simple":"...","complex":"..."}'
-${h("Apps")}
-    openmates apps list                                 Same as Apps
-    openmates apps <app-id>                             App details
-    \x1B[2mWeb: ${s("app_store")}\x1B[0m
-${h("Mates")}
-    \x1B[2m${s("mates")}\x1B[0m
-${h("Memories & app settings")}
-    openmates settings memories list [--app-id <id>] [--item-type <type>] [--json]
-    openmates settings memories types [--app-id <id>] [--json]
-    openmates settings memories create --app-id <id> --item-type <type> --data '<json>'
-    openmates settings memories update --id <id> --app-id <id> --item-type <type> --data '<json>'
-    openmates settings memories delete --id <entry-id>
-${h("Developers")}
-    openmates settings get api-keys [--json]            List API keys
-    openmates settings delete api-keys/<key-id>         Revoke API key
-    \x1B[2mCreate API key (shows secret once): ${s("developers/api-keys")}\x1B[0m
-    \x1B[2mManage devices: ${s("developers/devices")}\x1B[0m
-${h("Support")}
-    openmates settings post issues --data '<json>'      Report an issue
-
-\x1B[2mWeb app only (security \u2014 manage in browser):\x1B[0m
-  \x1B[2mPasskeys:   ${s("account/security/passkeys")}\x1B[0m
-  \x1B[2mPassword:   ${s("account/security/password")}\x1B[0m
-  \x1B[2m2FA:        ${s("account/security/2fa")}\x1B[0m
-  \x1B[2mSessions:   ${s("account/security/sessions")}\x1B[0m`);
+  const title = filter && filter.length > 0 ? `Settings: ${filter.join(" ")}` : "Settings";
+  header(title);
+  console.log("Predefined commands only. Raw settings get/post/patch/delete is not supported.\n");
+  if (commands.length === 0) {
+    console.log("No matching settings commands.");
+    return;
+  }
+  for (const command of commands) {
+    const isInfoOnly = SETTINGS_INFO_COMMANDS.includes(command);
+    const label = `openmates settings ${command.path.join(" ")}`;
+    process.stdout.write(`  ${label.padEnd(58)} ${command.description}`);
+    if (isInfoOnly) process.stdout.write(" \x1B[2m(info/web-only)\x1B[0m");
+    process.stdout.write("\n");
+    if (filter && filter.length > 0) {
+      for (const example of command.examples) process.stdout.write(`      e.g. ${example}
+`);
+      if (command.webPath) process.stdout.write(`      web: ${appUrl}/#settings/${command.webPath}
+`);
+    }
+  }
+  console.log("\nUse --help after a group for examples, e.g. openmates settings billing --help");
 }
 function printNewChatSuggestionsHelp() {
   console.log(`New chat suggestions command: