@synapsor/client 0.1.1 → 0.1.3

package/README.md

@@ -45,7 +45,7 @@ npm install @synapsor/client
 ```js
 import { Synapsor } from "@synapsor/client";
 
-const db = await Synapsor.connect("https://dev-api.synapsor.ai", {
+const db = await Synapsor.connect("https://synapsor.ai", {
   apiKey: process.env.SYNAPSOR_API_KEY,
 });
 
@@ -61,11 +61,112 @@ const ctx = await db.invokeAgentCapability("chat.prepare_llm_context", { questio
 
 Use database-scoped API keys from the Synapsor control panel for hosted projects.
 
+## Agent Workflows
+
+Use `agentRuns` when an agent framework owns routing, but Synapsor should own
+the durable workflow contract: session scope, capability calls, evidence,
+proposal branches, outbox actions, settlement, and replay.
+
+```js
+const run = await db.agentRuns.start({
+  workflow: "billing.late_fee_waiver_flow",
+  version: "2026-05-27",
+  input: { user_request: "Can we waive this late fee?" },
+});
+
+const answer = await run.invokeCapability("support.answer_ticket_question", {
+  stepKey: "answer_ticket_question",
+  arguments: { question: "Can we waive this late fee?" },
+  responseEnvelope: true,
+});
+
+const proposal = await run.invokeCapability("billing.propose_late_fee_waiver", {
+  stepKey: "propose_waiver",
+  arguments: { amount_cents: 2500 },
+  mode: "propose_only",
+  autoBranch: true,
+  responseEnvelope: true,
+});
+
+const action = await run.proposeExternalAction("stripe.issue_refund", {
+  stepKey: "refund_customer",
+  arguments: { charge_id: "ch_123", amount_cents: 2500 },
+  idempotencyKey: "refund:TCK_1001:2500",
+});
+
+await run.checkpoint("before_worker_claim", {
+  payload: { reason: "external action queued" },
+});
+await run.complete({ decision: "waiver_proposed" }, { status: "waiting_approval" });
+const graph = await run.explain();
+```
+
+Replay a stored capability run by using the numeric `agent_run_id` returned by
+Synapsor. Deterministic replay returns the captured persisted run; comparison
+modes can inspect the original snapshot, current state, a commit version, a
+timestamp, or a review branch.
+
+```js
+const replay = await db.replayAgentRun(123, {
+  mode: "original_snapshot",
+});
+
+const branchReplay = await db.replayAgentRun(123, {
+  mode: "branch",
+  branchName: "review_run_123",
+});
+```
+
+Workers should claim and confirm side effects through the outbox namespace:
+
+```js
+const task = await db.externalActions.claim({
+  queue: "billing_external_actions",
+  workerId: "billing-worker-1",
+});
+await db.externalActions.confirm(task.action_instance_id, {
+  status: "succeeded",
+  providerRequestId: "re_456",
+  response: { status: "succeeded" },
+});
+```
+
+## External DB Writeback Worker
+
+For existing Postgres/MySQL integrations, keep Synapsor in proposal mode. The
+agent stages an evidence-backed external write proposal, a human or settlement
+policy approves it, and a trusted worker in your app environment applies the
+approved change back to your existing database with parameterized SQL.
+
+```js
+import { createExternalDbWritebackWorker } from "@synapsor/client/external-db-writeback";
+
+const worker = createExternalDbWritebackWorker({
+  synapsorApiKey: process.env.SYNAPSOR_API_KEY,
+  sourceName: "app_postgres",
+  execute: async ({ sql, params }) => {
+    // Use your own Postgres/MySQL client here. The model never provides SQL.
+    return appDb.query(sql, params);
+  },
+});
+
+await worker.pollOnce();
+```
+
+The worker validates Synapsor-provided mapping metadata, only writes allowlisted
+columns, adds tenant and primary-key guards, checks optional conflict columns,
+and reports `applied`, `conflict`, or `failed` back to Synapsor idempotently.
+
 ## API Surface
 
 - `execute(sql)` and `query(sql)`
 - `setSession({...})`
 - `invokeAgentCapability(name, args, options)`
+- `agentRuns.start(...)`, `run.invokeCapability(...)`, `run.checkpoint(...)`, `run.complete(...)`, `run.explain(...)`
+- `replayAgentRun(id, { mode, version, timestamp, branchName })`
+- `externalActions.claim(...)` and `externalActions.confirm(...)`
+- `createAgentEval(...)` / `evals.create(...)` for run-history or `sourceTable` dataset evals
+- `evals.run(...).failures()`
 - `listCapabilities(query)`
 - `rememberFact({...})`
 - `proposeMemoryFact({...})`
@@ -77,6 +178,10 @@ Use database-scoped API keys from the Synapsor control panel for hosted projects
 - `checkFactForAction({...})`
 - branch helpers: `createBranch`, `useBranch`, `diffBranch`, `mergeBranch`, `dropBranch`
 - write lifecycle helpers: `previewWrite`, `approveWrite`, `commitWrite`, `rejectWrite`, `settleWrite`
+- external DB writeback worker: `createExternalDbWritebackWorker` from `@synapsor/client/external-db-writeback`
 - `readResource(uri)`
 
-Errors from Synapsor become `SynapsorError` with `status` and `payload`.
+Errors from Synapsor become `SynapsorError` with `status`, `code`,
+`requestId`, `retryable`, and the raw `payload`. Include `requestId` when
+opening support or incident tickets so server, gateway, and runtime logs can be
+joined without exposing secrets.

package/bin/synapsor.mjs

@@ -0,0 +1,442 @@
+#!/usr/bin/env node
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const PACKAGE_VERSION = "0.1.2";
+const DEFAULT_BASE_URL = "https://synapsor.ai";
+const ERROR_HINTS = new Map([
+  ["AUTH_REQUIRED", "Set SYNAPSOR_API_KEY or run `synapsor config set api-key`."],
+  ["BILLING_REQUIRED", "Builder resources require active or trialing Builder billing."],
+  ["LIMIT_EXCEEDED", "You reached a controlled-beta hard limit. Upgrade or reduce usage."],
+  ["FORBIDDEN", "The API key is not allowed to perform this operation."],
+  ["NOT_FOUND", "Check the project, database, handle, or run id."],
+  ["BETA_UNAVAILABLE", "This feature is not self-serve in the controlled beta."],
+]);
+
+function configPath() {
+  const override = process.env.SYNAPSOR_CLI_CONFIG_HOME;
+  return join(override || join(homedir(), ".config"), "synapsor", "config.json");
+}
+
+async function loadConfig(profile = "default") {
+  const path = configPath();
+  if (!existsSync(path)) return { path, profile, data: {}, current: {} };
+  const raw = JSON.parse(await readFile(path, "utf8"));
+  const profiles = raw.profiles && typeof raw.profiles === "object" ? raw.profiles : {};
+  return { path, profile, data: raw, current: profiles[profile] || {} };
+}
+
+async function saveConfig(profile, patch) {
+  const existing = await loadConfig(profile);
+  const data = existing.data.profiles ? existing.data : { profiles: {} };
+  data.profiles[profile] = { ...(data.profiles[profile] || {}), ...patch };
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Best effort on platforms without POSIX modes.
+  }
+  return path;
+}
+
+function parse(argv) {
+  const globals = { json: false, profile: "default", project: "", db: "", baseUrl: "" };
+  const args = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      const next = argv[i + 1] || "";
+      if (/^\s*[\[{]/.test(next)) {
+        args.push(arg);
+        args.push(argv[++i]);
+      } else {
+        globals.json = true;
+      }
+    }
+    else if (arg === "--yes" || arg === "-y") globals.yes = true;
+    else if (["--profile", "--project", "--db", "--base-url"].includes(arg)) {
+      const key = arg === "--base-url" ? "baseUrl" : arg.slice(2);
+      globals[key] = argv[++i] || "";
+    }
+    else args.push(arg);
+  }
+  return { globals, args };
+}
+
+function redact(value) {
+  const text = String(value || "");
+  if (!text) return "";
+  return `${text.slice(0, 8)}...redacted`;
+}
+
+function print(payload, globals) {
+  if (globals.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (Array.isArray(payload)) {
+    for (const item of payload) console.log(formatLine(item));
+    return;
+  }
+  if (payload && typeof payload === "object") {
+    console.log(formatLine(payload));
+    return;
+  }
+  console.log(String(payload));
+}
+
+function formatLine(item) {
+  if (!item || typeof item !== "object") return String(item);
+  const preferred = ["project_id", "database_id", "name", "plan", "status", "billing_status", "runtime_branch", "key_id"];
+  const parts = [];
+  for (const key of preferred) {
+    if (item[key] !== undefined && item[key] !== null && item[key] !== "") parts.push(`${key}=${item[key]}`);
+  }
+  return parts.length ? parts.join("  ") : JSON.stringify(item);
+}
+
+async function requireApiKey(config) {
+  const key = process.env.SYNAPSOR_API_KEY || config.current.apiKey || "";
+  if (!key) {
+    const error = new Error("AUTH_REQUIRED: configure an API key from the Synapsor dashboard. Public demo: https://synapsor.ai/demo");
+    error.code = "AUTH_REQUIRED";
+    throw error;
+  }
+  return key;
+}
+
+async function client(globals) {
+  const config = await loadConfig(globals.profile);
+  const baseUrl = (globals.baseUrl || process.env.SYNAPSOR_BASE_URL || config.current.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const apiKey = await requireApiKey(config);
+  return { baseUrl, apiKey };
+}
+
+async function request(globals, method, path, body) {
+  const { baseUrl, apiKey } = await client(globals);
+  const init = { method, headers: { accept: "application/json", authorization: `Bearer ${apiKey}` } };
+  if (body !== undefined) {
+    init.headers["content-type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  const response = await fetch(`${baseUrl}${path}`, init);
+  const text = await response.text();
+  let payload = {};
+  if (text.trim()) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { ok: false, error: "INVALID_JSON_RESPONSE", body_preview: text.slice(0, 240) };
+    }
+  }
+  if (!response.ok || payload.ok === false) {
+    const errorCode = mapError(payload.error || response.status);
+    const error = new Error(`${errorCode}: ${payload.message || payload.error || `HTTP ${response.status}`}`);
+    error.code = errorCode;
+    error.payload = payload;
+    throw error;
+  }
+  return payload;
+}
+
+function mapError(error) {
+  const text = String(error || "").toLowerCase();
+  if (text.includes("auth") || text.includes("session") || text.includes("token")) return "AUTH_REQUIRED";
+  if (text.includes("payment") || text.includes("billing")) return "BILLING_REQUIRED";
+  if (text.includes("quota") || text.includes("limit")) return "LIMIT_EXCEEDED";
+  if (text.includes("denied") || text.includes("forbidden")) return "FORBIDDEN";
+  if (text.includes("not_found")) return "NOT_FOUND";
+  if (text.includes("plan_not_available")) return "BETA_UNAVAILABLE";
+  return String(error || "REQUEST_FAILED").toUpperCase();
+}
+
+function flagValue(args, names, fallback = "") {
+  const aliases = Array.isArray(names) ? names : [names];
+  for (let i = 0; i < args.length; i += 1) {
+    if (aliases.includes(args[i])) return args[i + 1] || fallback;
+  }
+  return fallback;
+}
+
+function csvFlag(args, name) {
+  const value = flagValue(args, name, "");
+  return value ? value.split(",").map((item) => item.trim()).filter(Boolean) : [];
+}
+
+function resolveSecretRef(value) {
+  const text = String(value || "").trim();
+  if (text.startsWith("env:")) {
+    const envName = text.slice(4);
+    const resolved = process.env[envName] || "";
+    if (!resolved) throw new Error(`SECRET_ENV_REQUIRED: ${envName} is not set`);
+    return resolved;
+  }
+  return text;
+}
+
+function scopedProject(globals) {
+  return globals.project || process.env.SYNAPSOR_PROJECT_ID || "";
+}
+
+function scopedDatabase(globals) {
+  return globals.db || process.env.SYNAPSOR_DATABASE_ID || "";
+}
+
+async function resolveSourceId(globals, nameOrId) {
+  const text = String(nameOrId || "").trim();
+  if (!text) throw new Error("SOURCE_REQUIRED: provide an external source name or source_id");
+  if (text.startsWith("src_")) return text;
+  const query = scopedProject(globals) ? `?project_id=${encodeURIComponent(scopedProject(globals))}` : "";
+  const listed = await request(globals, "GET", `/v1/control/external-sources${query}`);
+  const match = (listed.sources || []).find((source) => source.name === text || source.source_id === text);
+  if (!match) throw new Error(`NOT_FOUND: external source not found: ${text}`);
+  return match.source_id;
+}
+
+async function confirm(globals, label) {
+  if (globals.yes) return;
+  const rl = createInterface({ input, output });
+  const answer = await rl.question(`${label} Type yes to continue: `);
+  rl.close();
+  if (answer.trim().toLowerCase() !== "yes") throw new Error("FORBIDDEN: confirmation required");
+}
+
+async function readStdinSecret() {
+  const rl = createInterface({ input, output });
+  const value = await rl.question("Paste Synapsor API key: ");
+  rl.close();
+  return value.trim();
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const { globals, args } = parse(argv);
+  const [cmd, sub, third, ...rest] = args;
+  if (!cmd || cmd === "--help" || cmd === "help") return help();
+  if (cmd === "--version" || cmd === "version") return console.log(PACKAGE_VERSION);
+
+  if (cmd === "config") {
+    if (sub === "get") {
+      const config = await loadConfig(globals.profile);
+      return print({ profile: globals.profile, baseUrl: config.current.baseUrl || DEFAULT_BASE_URL, apiKey: redact(process.env.SYNAPSOR_API_KEY || config.current.apiKey) }, globals);
+    }
+    if (sub === "set" && third === "base-url") {
+      const value = rest[0];
+      if (!value) throw new Error("BASE_URL_REQUIRED: usage `synapsor config set base-url https://synapsor.ai`");
+      await saveConfig(globals.profile, { baseUrl: value.replace(/\/+$/, "") });
+      return print({ ok: true, profile: globals.profile, baseUrl: value.replace(/\/+$/, "") }, globals);
+    }
+    if (sub === "set" && third === "api-key") {
+      const value = rest[0] || await readStdinSecret();
+      if (!value) throw new Error("AUTH_REQUIRED: API key required");
+      await saveConfig(globals.profile, { apiKey: value });
+      return print({ ok: true, profile: globals.profile, apiKey: redact(value) }, globals);
+    }
+  }
+
+  if (cmd === "projects") {
+    if (sub === "list") {
+      const payload = await request(globals, "GET", "/v1/control/projects");
+      return print(payload.projects || [], globals);
+    }
+    if (sub === "create") {
+      const name = third;
+      if (!name) throw new Error("PROJECT_NAME_REQUIRED: usage `synapsor projects create <name>`");
+      return print(await request(globals, "POST", "/v1/control/projects", { name, plan: "free" }), globals);
+    }
+  }
+
+  if (cmd === "db") {
+    if (sub === "list") {
+      const payload = await request(globals, "GET", "/v1/control/databases");
+      return print(payload.databases || [], globals);
+    }
+    if (sub === "create") {
+      const name = third;
+      if (!name) throw new Error("DATABASE_NAME_REQUIRED: usage `synapsor db create <name> --project <project>`");
+      return print(await request(globals, "POST", "/v1/control/databases", { name, project_id: globals.project, plan: "free" }), globals);
+    }
+  }
+
+  if (cmd === "sources") {
+    if (sub === "list") {
+      const query = scopedProject(globals) ? `?project_id=${encodeURIComponent(scopedProject(globals))}` : "";
+      const payload = await request(globals, "GET", `/v1/control/external-sources${query}`);
+      return print(payload.sources || [], globals);
+    }
+    if (sub === "show") {
+      const sourceId = await resolveSourceId(globals, third);
+      return print(await request(globals, "GET", `/v1/control/external-sources/${encodeURIComponent(sourceId)}`), globals);
+    }
+    if (sub === "create" && ["postgres", "mysql"].includes(third)) {
+      const kind = third;
+      const defaultName = kind === "mysql" ? "app_mysql" : "app_postgres";
+      const envHint = kind === "mysql" ? "APP_MYSQL_URL" : "APP_POSTGRES_URL";
+      const name = flagValue(rest, "--name", defaultName);
+      const url = resolveSecretRef(flagValue(rest, "--url", ""));
+      const ssl = flagValue(rest, "--ssl", "require");
+      const mode = flagValue(rest, "--mode", "read-only");
+      const projectId = scopedProject(globals);
+      const databaseId = scopedDatabase(globals);
+      if (!projectId || !databaseId) throw new Error("PROJECT_AND_DATABASE_REQUIRED: use --project <project_id> --db <database_id> or SYNAPSOR_PROJECT_ID/SYNAPSOR_DATABASE_ID");
+      if (!url) throw new Error(`${kind.toUpperCase()}_URL_REQUIRED: usage \`synapsor sources create ${kind} --name ${defaultName} --url env:${envHint} --project <project> --db <database>\``);
+      return print(await request(globals, "POST", "/v1/control/external-sources", {
+        project_id: projectId,
+        database_id: databaseId,
+        kind,
+        name,
+        connection: { url, ssl_mode: ssl },
+        mode,
+      }), globals);
+    }
+    if (["test", "inspect", "generate", "doctor", "disable"].includes(sub)) {
+      const sourceId = await resolveSourceId(globals, third);
+      if (sub === "test") return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/test`, {}), globals);
+      if (sub === "inspect") {
+        const schema = flagValue(rest, "--schema", "public");
+        const database = flagValue(rest, "--database", "");
+        const payload = database ? { database, include_views: true } : { schemas: [schema], include_views: true };
+        return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/inspect`, payload), globals);
+      }
+      if (sub === "generate") {
+        const generated = await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/generate`, {
+          template: flagValue(rest, "--template", "support-ticket-agent"),
+          namespace: flagValue(rest, "--namespace", "support"),
+        });
+        const outDir = flagValue(rest, "--out", "");
+        if (outDir && Array.isArray(generated.files)) {
+          await mkdir(outDir, { recursive: true });
+          const written = [];
+          for (const file of generated.files) {
+            const relative = String(file.path || "generated.txt").replace(/^[/\\]+/, "").replace(/\.\.[/\\]/g, "");
+            const path = join(outDir, relative);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, String(file.contents || ""));
+            written.push(path);
+          }
+          return print({ ok: true, source_id: generated.source_id, capability: generated.capability, out: outDir, files_written: written }, globals);
+        }
+        return print(generated, globals);
+      }
+      if (sub === "doctor") {
+        const database = flagValue(rest, "--database", "");
+        const payload = database ? { database } : { schemas: [flagValue(rest, "--schema", "public")] };
+        return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/doctor`, payload), globals);
+      }
+      await confirm(globals, "Disabling an external source blocks future reads but keeps audit/evidence history.");
+      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/disable`, {}), globals);
+    }
+    if (sub === "import") {
+      const sourceId = await resolveSourceId(globals, third);
+      const schema = flagValue(rest, "--schema", "public");
+      const database = flagValue(rest, "--database", "");
+      const tables = csvFlag(rest, "--tables");
+      const tenantColumn = flagValue(rest, "--tenant-column", "");
+      const mode = flagValue(rest, "--mode", "live-read");
+      if (!tables.length) throw new Error("TABLES_REQUIRED: pass --tables tickets,customers,policy_chunks");
+      if (!tenantColumn && !rest.includes("--single-tenant")) throw new Error("TENANT_COLUMN_REQUIRED: pass --tenant-column tenant_id or --single-tenant");
+      return print(await request(globals, "POST", `/v1/control/external-sources/${encodeURIComponent(sourceId)}/import`, {
+        tables: tables.map((table) => ({
+          ...(database ? { database } : {}),
+          schema,
+          name: table,
+          alias_schema: flagValue(rest, "--alias-schema", database ? "external_shop" : "external_support"),
+          alias_name: table,
+          tenant_column: tenantColumn || undefined,
+          single_tenant: rest.includes("--single-tenant"),
+          mode,
+        })),
+      }), globals);
+    }
+  }
+
+  if (cmd === "sql") {
+    const db = globals.db || "";
+    let sql = args.slice(1).join(" ").trim();
+    const fileIndex = args.indexOf("--file");
+    if (fileIndex >= 0) sql = await readFile(args[fileIndex + 1], "utf8");
+    if (!db) throw new Error("DATABASE_REQUIRED: use `--db <database_id>`");
+    if (!sql) throw new Error("SQL_REQUIRED: pass SQL after --db or use --file");
+    return print(await request(globals, "POST", "/v1/control/console/sql", { project_id: globals.project, database_id: db, sql }), globals);
+  }
+
+  if (cmd === "invoke") {
+    const capability = sub;
+    const jsonIndex = args.indexOf("--json");
+    const body = jsonIndex >= 0 ? JSON.parse(args[jsonIndex + 1] || "{}") : {};
+    if (!capability) throw new Error("CAPABILITY_REQUIRED: usage `synapsor invoke <capability> --db <database> --json '{...}'`");
+    if (!globals.db) throw new Error("DATABASE_REQUIRED: use `--db <database_id>`");
+    return print(await request(globals, "POST", "/v1/control/console/invoke", { project_id: globals.project, database_id: globals.db, capability, arguments: body }), globals);
+  }
+
+  if (cmd === "evidence" && sub === "get") {
+    if (!third || !globals.db) throw new Error("EVIDENCE_OR_DATABASE_REQUIRED: usage `synapsor evidence get <handle> --db <database>`");
+    return print(await request(globals, "POST", "/v1/control/console/evidence", { project_id: globals.project, database_id: globals.db, uri: third }), globals);
+  }
+
+  if (cmd === "proposal" && ["preview", "approve", "reject"].includes(sub)) {
+    if (!third || !globals.db) throw new Error("PROPOSAL_OR_DATABASE_REQUIRED: usage `synapsor proposal preview <handle> --db <database>`");
+    if (sub !== "preview") await confirm(globals, `Proposal ${sub} is auditable and may change workflow state.`);
+    return print(await request(globals, "POST", `/v1/control/console/proposals/${sub}`, { project_id: globals.project, database_id: globals.db, proposal: third }), globals);
+  }
+
+  if (cmd === "replay") {
+    if (!sub || !globals.db) throw new Error("RUN_OR_DATABASE_REQUIRED: usage `synapsor replay <run-id> --db <database>`");
+    return print(await request(globals, "POST", "/v1/control/console/replay", { project_id: globals.project, database_id: globals.db, run_id: sub }), globals);
+  }
+
+  throw new Error(`UNKNOWN_COMMAND: ${args.join(" ")}`);
+}
+
+function help() {
+  console.log(`Synapsor CLI ${PACKAGE_VERSION}
+
+Usage:
+  synapsor --version
+  synapsor config set base-url https://synapsor.ai
+  synapsor config set api-key
+  synapsor config get
+  synapsor projects list
+  synapsor projects create <name>
+  synapsor db list --project <project>
+  synapsor db create <name> --project <project>
+  synapsor sources create postgres --name app_postgres --url env:APP_POSTGRES_URL --ssl require --mode read-only --project <project> --db <database>
+  synapsor sources create mysql --name app_mysql --url env:APP_MYSQL_URL --ssl require --mode read-only --project <project> --db <database>
+  synapsor sources test app_postgres --project <project>
+  synapsor sources inspect app_postgres --schema public --project <project>
+  synapsor sources inspect app_mysql --database shopdb --project <project>
+  synapsor sources import app_postgres --schema public --tables tickets,customers,policy_chunks --tenant-column tenant_id --project <project>
+  synapsor sources import app_mysql --database shopdb --tables orders,customers,refund_policies --tenant-column tenant_id --project <project>
+  synapsor sources generate app_postgres --template support-ticket-agent --namespace support --project <project>
+  synapsor sources generate app_mysql --template ecommerce-order-agent --namespace ecommerce --project <project>
+  synapsor sources list --project <project>
+  synapsor sources show app_postgres --project <project>
+  synapsor sources doctor app_postgres --project <project>
+  synapsor sources disable app_postgres --project <project> --yes
+  synapsor sql --db <database> "SELECT 1;"
+  synapsor sql --db <database> --file ./query.sql
+  synapsor invoke <capability> --db <database> --json '{"ticket_id":"TICK-1001"}'
+  synapsor evidence get <evidence-handle> --db <database>
+  synapsor proposal preview <proposal-handle> --db <database>
+  synapsor proposal approve <proposal-handle> --db <database> --yes
+  synapsor proposal reject <proposal-handle> --db <database> --yes
+  synapsor replay <run-id> --db <database>
+
+Environment:
+  SYNAPSOR_API_KEY, SYNAPSOR_BASE_URL
+
+Synapsor CLI runs Synapsor SQL/API commands only. It never executes server shell commands.`);
+}
+
+main().catch((error) => {
+  const code = error.code || String(error.message || "REQUEST_FAILED").split(":", 1)[0];
+  console.error(error.message || String(error));
+  if (ERROR_HINTS.has(code)) console.error(ERROR_HINTS.get(code));
+  process.exitCode = 1;
+});