@aiaiai-pt/martha-cli 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -4,11 +4,11 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 
 ## [Unreleased]
 
-### Changed — 0.5.1 CLI onboarding feedback
-- `martha init` now defaults to the local preset; the hosted Martha cloud profile remains available through explicit `--preset cloud` and uses `keycloak.frank.nomadriver.co`.
-- CLI version output now reads `martha-cli/package.json` instead of a second hardcoded literal.
-- `martha agents create` exposes `--system-prompt` as the primary inline flag and keeps `--prompt` as a compatibility alias.
-- CLI docs and bundled agent skill now explain explicit customer profile setup, `system_prompt`, and the normal chat-client agent grant-as-tool path.
+## [0.7.0] — 2026-06-09
+
+### Added — #522 bulk-ingest observability + management
+- `document-sync sources status <id>` — ingestion progress for a source: counts by status (pending / ingesting / ready / error), recent drain rate, naive ETA, and the top grouped error reasons. `--window-minutes` tunes the rate window; JSON mode emits the raw summary.
+- `documents retry --collection <id-or-slug-or-name> --status error [--yes]` — re-drive a collection's failed documents (subtree-scoped). Bounded + idempotent: flips matching docs back to `pending` for the ingestion reconciler to re-drive through the per-tenant quota gate at its capped rate (no thundering herd). Non-TTY requires `--yes`; JSON mode emits the result. `--status pending` re-drives stuck-pending docs.
 
 ### Added — #407 connections command (service-account Drive auth)
 - `martha connections create|list|update|test|delete` — manage Vault-backed integration connections from the CLI (previously admin-UI / raw-curl only). `create` mirrors `POST /api/admin/connections`; `update` mirrors `PUT`.
@@ -34,7 +34,7 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 First-run UX for third-party developers and agent runtimes.
 
 ### Added
-- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + keycloak.frank.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
+- `martha init` — interactive wizard that writes a profile to `~/.martha/config.yaml`. Two presets: `cloud` (martha.nomadriver.co + auth.nomadriver.co) and `local` (localhost:8080 + 8180). Idempotent with `--force`; rejects overwrites without it.
 - `martha doctor` — five-check diagnostic: API health, API/CLI version skew (via the new `GET /api/version` endpoint), Keycloak OIDC discovery, stored token validity, authenticated request. Exits non-zero only on FAIL, not WARN.
 - `martha skill` — prints the bundled `SKILL.md` to stdout. Agent runtimes that don't read filesystems by convention can now seed prompt context with `npx -y @aiaiai-pt/martha-cli@0.3.0 skill | head -200`.
 

package/README.md

@@ -15,7 +15,7 @@ npx -y @aiaiai-pt/martha-cli@latest --help
 Pin a version when calling from CI or agent runtimes:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.5.1 agents list --json
+npx -y @aiaiai-pt/martha-cli@0.2.0 agents list --json
 ```
 
 ### Install globally
@@ -31,12 +31,9 @@ Requires Node.js >= 22.
 
 ```bash
 # 1. Configure a profile — writes ~/.martha/config.yaml
-martha init                       # interactive, local preset by default
-martha init --preset cloud        # martha.nomadriver.co + keycloak.frank.nomadriver.co
-martha init --no-interactive --name acme \
-  --api-url https://martha.acme.example \
-  --keycloak-url https://auth.acme.example \
-  --keycloak-realm acme           # scripted customer profile
+martha init                       # interactive (defaults to cloud preset)
+martha init --preset local        # localhost dev stack
+martha init --no-interactive --name staging --api-url https://...   # scripted
 
 # 2. Authenticate
 martha auth login                 # browser flow (PKCE)
@@ -59,19 +56,15 @@ Full command reference: `martha --help` (or any subcommand `--help`).
 Profiles live at `~/.martha/config.yaml`. Each profile defines:
 
 ```yaml
-current_profile: local
+current_profile: default
 profiles:
-  local:
-    api_url: http://localhost:8080
-    keycloak_url: http://localhost:8180
+  default:
+    api_url: https://martha.nomadriver.co
+    keycloak_url: https://auth.nomadriver.co
     keycloak_realm: frank
     auth_type: oidc
 ```
 
-Install does not create or mutate `~/.martha/config.yaml`. Run `martha init`
-or set `MARTHA_API_URL`, `MARTHA_KEYCLOAK_URL`, and
-`MARTHA_KEYCLOAK_REALM` explicitly for your deployment.
-
 Override per-command:
 
 ```bash
@@ -109,32 +102,12 @@ martha skill
 npx -y @aiaiai-pt/martha-cli@latest skill | head -200
 ```
 
-Agent YAML should use `system_prompt` for the durable agent instruction. To
-make an agent callable from a chat client, grant the agent to that client; the
-chat model will call it as a tool:
-
-```yaml
-kind: Agent
-name: support-bot
-system_prompt: You help customers resolve support tickets.
-llm_config:
-  provider: anthropic
-  model: claude-sonnet-4-6
-loop_config:
-  max_iterations: 10
-```
-
-```bash
-martha definitions apply -f support-bot.yaml --yes
-martha clients grant web-chat agent support-bot
-```
-
 ## Stability
 
 `0.x` releases may change CLI flags or JSON output between minor versions. Pin a version in CI/agent contexts:
 
 ```bash
-npx -y @aiaiai-pt/martha-cli@0.5.1 ...
+npx -y @aiaiai-pt/martha-cli@0.3.0 ...
 ```
 
 `1.0.0` will commit to a stable contract — see the [tracking issue](https://github.com/westeuropeco/martha/issues/292).

package/dist/index.js

@@ -5,25 +5,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1001,7 +1019,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -11025,31 +11043,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-import fs5 from "node:fs";
-import path4 from "node:path";
-import { fileURLToPath } from "node:url";
-function readPackageVersion() {
-  let dir = path4.dirname(fileURLToPath(import.meta.url));
-  for (let i = 0;i < 5; i += 1) {
-    const packagePath = path4.join(dir, "package.json");
-    if (fs5.existsSync(packagePath)) {
-      try {
-        const parsed = JSON.parse(fs5.readFileSync(packagePath, "utf-8"));
-        if (parsed.name === "@aiaiai-pt/martha-cli" && parsed.version) {
-          return parsed.version;
-        }
-      } catch {
-        return "0.0.0-dev";
-      }
-    }
-    const parent = path4.dirname(dir);
-    if (parent === dir)
-      break;
-    dir = parent;
-  }
-  return "0.0.0-dev";
-}
-var CLI_VERSION = readPackageVersion();
+var CLI_VERSION = "0.3.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11111,8 +11105,7 @@ function printSessionTable(sessions) {
     { header: "LAST ACTIVE", accessor: (r) => r.active },
     { header: "CLIENT", accessor: (r) => r.client }
   ];
-  const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
-  const stripAnsi = (s) => s.replace(ansiPattern, "");
+  const stripAnsi = (s) => s.replace(/\x1B\[[0-9;]*m/g, "");
   const widths = cols.map((col) => Math.max(col.header.length, ...rows.map((r) => stripAnsi(col.accessor(r)).length)));
   const header = cols.map((col, i) => col.header.padEnd(widths[i])).join("  ");
   console.log(source_default.bold(header));
@@ -11886,7 +11879,7 @@ function registerConfigCommand(program2) {
       config.current_profile = name;
     }
     saveConfig(config);
-    if (program2.opts().json) {
+    if (!!program2.opts().json) {
       console.log(JSON.stringify({
         name,
         profile,
@@ -11930,7 +11923,7 @@ function registerConfigCommand(program2) {
       config.current_profile = remaining[0] ?? "default";
     }
     saveConfig(config);
-    if (program2.opts().json) {
+    if (!!program2.opts().json) {
       console.log(JSON.stringify({ name, deleted: true }));
       return;
     }
@@ -11939,8 +11932,8 @@ function registerConfigCommand(program2) {
 }
 
 // src/commands/definitions-apply.ts
-import fs6 from "node:fs";
-import path5 from "node:path";
+import fs5 from "node:fs";
+import path4 from "node:path";
 init_dist();
 init_errors();
 var VALID_KINDS = new Set(["Function", "Workflow", "Agent"]);
@@ -11975,20 +11968,20 @@ var SERVER_GENERATED_FIELDS = new Set([
 ]);
 var AGENT_MANAGED_FIELDS = new Set(["functions", "workflows"]);
 function loadDefinitions(inputPath) {
-  const resolved = path5.resolve(inputPath);
-  if (!fs6.existsSync(resolved)) {
+  const resolved = path4.resolve(inputPath);
+  if (!fs5.existsSync(resolved)) {
     throw new CLIError(`Path not found: ${inputPath}`, 1 /* Error */);
   }
-  const stat = fs6.statSync(resolved);
+  const stat = fs5.statSync(resolved);
   if (stat.isDirectory()) {
     return loadDirectory(resolved);
   }
   return loadFile(resolved);
 }
 function loadDirectory(dirPath) {
-  const entries = fs6.readdirSync(dirPath).sort();
+  const entries = fs5.readdirSync(dirPath).sort();
   const validExts = new Set([".yaml", ".yml", ".json"]);
-  const files = entries.filter((e) => validExts.has(path5.extname(e).toLowerCase())).map((e) => path5.join(dirPath, e));
+  const files = entries.filter((e) => validExts.has(path4.extname(e).toLowerCase())).map((e) => path4.join(dirPath, e));
   if (files.length === 0) {
     throw new CLIError(`No YAML or JSON files found in ${dirPath}`, 4 /* Validation */);
   }
@@ -11999,8 +11992,8 @@ function loadDirectory(dirPath) {
   return results;
 }
 function loadFile(filePath) {
-  const content = fs6.readFileSync(filePath, "utf-8");
-  const ext = path5.extname(filePath).toLowerCase();
+  const content = fs5.readFileSync(filePath, "utf-8");
+  const ext = path4.extname(filePath).toLowerCase();
   if (ext === ".json") {
     const parsed = parseJsonFile(content, filePath);
     return [toLocalDefinition(parsed, filePath)];
@@ -12422,7 +12415,7 @@ Examples:
 }
 
 // src/commands/definitions-export.ts
-import fs7 from "node:fs";
+import fs6 from "node:fs";
 init_errors();
 async function exportDefinitions(ctx, opts, isJsonMode) {
   const params = {};
@@ -12438,7 +12431,7 @@ async function exportDefinitions(ctx, opts, isJsonMode) {
   const text = await res.text();
   if (opts.output) {
     try {
-      fs7.writeFileSync(opts.output, text);
+      fs6.writeFileSync(opts.output, text);
     } catch (err) {
       throw new CLIError(`Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`, 1 /* Error */);
     }
@@ -13036,7 +13029,6 @@ Usage: martha workflows execute ${name} --inputs '${JSON.stringify(Object.fromEn
       label: n.label || "-",
       connections: (outgoing.get(n.id) ?? []).join(", ") || "-"
     }));
-    const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
     const cols = [
       { header: "ID", accessor: (r) => r.id, raw: (r) => r.id },
       { header: "TYPE", accessor: (r) => r.type, raw: (r) => r.type },
@@ -13044,7 +13036,7 @@ Usage: martha workflows execute ${name} --inputs '${JSON.stringify(Object.fromEn
       {
         header: "CONNECTIONS",
         accessor: (r) => r.connections,
-        raw: (r) => (outgoing.get(r.id) ?? []).map((t) => t.replace(ansiPattern, "")).join(", ") || "-"
+        raw: (r) => (outgoing.get(r.id) ?? []).map((t) => t.replace(/\x1B\[[0-9;]*m/g, "")).join(", ") || "-"
       }
     ];
     const widths = cols.map((col) => Math.max(col.header.length, ...rows.map((r) => col.raw(r).length)));
@@ -13162,8 +13154,8 @@ function registerProjectionCommands(parentCmd, getCtx, isJson) {
       } catch {}
     }
     if (opts.output) {
-      const fs8 = await import("node:fs/promises");
-      await fs8.writeFile(opts.output, toWrite, "utf-8");
+      const fs7 = await import("node:fs/promises");
+      await fs7.writeFile(opts.output, toWrite, "utf-8");
       if (!isJson()) {
         console.error(source_default.dim(`Wrote ${format} projection of '${name}' to ${opts.output}`));
       }
@@ -13326,20 +13318,16 @@ var agentsConfig = {
   },
   normalizeBody: normalizeAgentBody,
   extraCreateOptions: (cmd) => {
-    cmd.option("--name <name>", "Agent name").option("--type <type>", "Agent type (cloud or external)", "cloud").option("--model <model>", "LLM model (e.g. anthropic/claude-sonnet-4-6)").option("--provider <provider>", "LLM provider (anthropic, openai)").option("--system-prompt <text>", "System prompt").option("--prompt <text>", "Deprecated alias for --system-prompt").option("--description <text>", "Agent description").option("--temperature <n>", "Temperature (0-1)").option("--max-tokens <n>", "Max output tokens").option("--tags <tags>", "Capability domains (comma-separated)").option("--local-tools <tools>", "Local tools (comma-separated)").option("--auth <method>", "Auth method for external agents: service-account or api-key");
+    cmd.option("--name <name>", "Agent name").option("--type <type>", "Agent type (cloud or external)", "cloud").option("--model <model>", "LLM model (e.g. anthropic/claude-sonnet-4-6)").option("--provider <provider>", "LLM provider (anthropic, openai)").option("--prompt <text>", "System prompt").option("--description <text>", "Agent description").option("--temperature <n>", "Temperature (0-1)").option("--max-tokens <n>", "Max output tokens").option("--tags <tags>", "Capability domains (comma-separated)").option("--local-tools <tools>", "Local tools (comma-separated)").option("--auth <method>", "Auth method for external agents: service-account or api-key");
   },
   buildInlineBody: (opts) => {
     if (!opts.name)
       return null;
-    if (opts.systemPrompt && opts.prompt) {
-      throw new CLIError("Use only one of --system-prompt or --prompt.", 4 /* Validation */, "--prompt is a backwards-compatible alias; prefer --system-prompt.");
-    }
     const body = { name: opts.name };
     if (opts.description)
       body.description = opts.description;
-    const systemPrompt = opts.systemPrompt ?? opts.prompt;
-    if (systemPrompt)
-      body.system_prompt = systemPrompt;
+    if (opts.prompt)
+      body.system_prompt = opts.prompt;
     if (opts.type)
       body.agent_type = opts.type;
     if (opts.model)
@@ -13531,7 +13519,7 @@ Usage:
 };
 
 // src/commands/documents.ts
-import fs8 from "node:fs";
+import fs7 from "node:fs";
 init_errors();
 var TERMINAL_STATUSES2 = new Set(["ready", "error"]);
 var SPINNER_FRAMES2 = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -13777,6 +13765,7 @@ ${items.length} collections`));
     console.log(`  Status:    ${col.is_active !== false ? source_default.green("active") : source_default.dim("inactive")}`);
     console.log(`  Documents: ${col.document_count ?? 0}`);
     console.log(`  Storage:   ${col.storage_backend ?? "-"}`);
+    console.log(`  Drive:     ${col.drive_folder_id ? source_default.cyan(col.drive_folder_id) : source_default.dim("not linked")}`);
     if (col.total_size_bytes != null) {
       console.log(`  Size:      ${formatBytes(col.total_size_bytes)}`);
     }
@@ -13832,7 +13821,7 @@ ${items.length} collections`));
   });
   cmd.command("upload <collection-id> <file>").description("Upload a document to a collection").option("--wait", "Wait for ingestion to complete").option("--follow", "Follow ingestion progress in real time").action(async (collectionId, filePath, opts) => {
     const ctx = getCtx();
-    if (!fs8.existsSync(filePath)) {
+    if (!fs7.existsSync(filePath)) {
       throw new CLIError(`File not found: ${filePath}`, 4 /* Validation */);
     }
     const result = await ctx.api.upload(`/api/admin/collections/${encodeURIComponent(collectionId)}/documents`, filePath);
@@ -14147,10 +14136,79 @@ ${source_default.bold(`Sources (${result.sources.length} chunks):`)}`);
       }
     }
   });
+  cmd.command("retry").description("Re-drive ingestion for a collection's errored documents. Bounded " + "and idempotent — flips matching docs back to pending; the " + "ingestion reconciler re-drives them at its capped rate (no herd).").requiredOption("--collection <ref>", "Collection id, slug, or name").option("--status <status>", "Which docs to retry: error | pending", "error").option("--yes", "Skip confirmation (required in non-interactive mode)").action(async (opts) => {
+    if (!["error", "pending"].includes(opts.status)) {
+      throw new CLIError("--status must be one of: error, pending", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const collection = await resolveCollection(ctx, opts.collection);
+    if (!opts.yes) {
+      if (!process.stdin.isTTY) {
+        throw new CLIError("Cannot confirm in non-interactive mode. Use --yes to retry.", 1 /* Error */);
+      }
+      const ok = await confirm(`Retry ${opts.status} documents in '${collection.name}'?`);
+      if (!ok) {
+        if (isJson()) {
+          console.log(JSON.stringify({ reset_count: 0, cancelled: true }));
+        } else {
+          console.log("Cancelled.");
+        }
+        return;
+      }
+    }
+    const result = await ctx.api.post(`/api/admin/collections/${encodeURIComponent(collection.id)}/retry-ingestion`, undefined, { params: { status: opts.status } });
+    if (isJson()) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Re-drove ${result.reset_count} ${opts.status} document(s) in ` + `'${collection.name}'. The ingestion reconciler will pick them ` + `up within ~1 min (rate-limited by the per-tenant quota).`));
+  });
 }
 
 // src/commands/document-sync.ts
 init_errors();
+var VALID_MODES = ["polling", "evented", "manual"];
+function formatEta(seconds) {
+  if (seconds === null || seconds === undefined)
+    return "—";
+  if (seconds < 60)
+    return "<1m";
+  const mins = Math.round(seconds / 60);
+  if (mins < 60)
+    return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  const rem = mins % 60;
+  return rem ? `${hours}h ${rem}m` : `${hours}h`;
+}
+function progressBar(ready, total, width = 24) {
+  if (total <= 0)
+    return source_default.dim("·".repeat(width));
+  const filled = Math.min(width, Math.round(ready / total * width));
+  return source_default.green("█".repeat(filled)) + source_default.dim("░".repeat(width - filled));
+}
+function printIngestionStatus(sourceId, s) {
+  const c = s.counts;
+  const pct = s.total > 0 ? Math.round(c.ready / s.total * 100) : 0;
+  console.log(source_default.bold(`
+Ingestion status — source ${sourceId}`));
+  console.log(source_default.dim("-".repeat(48)));
+  console.log(`  ${progressBar(c.ready, s.total)}  ${pct}%  (${c.ready}/${s.total} ready)`);
+  console.log(`  ${source_default.yellow("pending")}   ${String(c.pending).padStart(6)}` + `   ${source_default.cyan("ingesting")} ${String(c.ingesting).padStart(6)}`);
+  console.log(`  ${source_default.green("ready")}     ${String(c.ready).padStart(6)}` + `   ${source_default.red("error")}     ${String(c.error).padStart(6)}`);
+  if (c.other > 0) {
+    console.log(`  ${source_default.dim("other")}     ${String(c.other).padStart(6)}`);
+  }
+  console.log(source_default.dim("-".repeat(48)));
+  console.log(`  Drain rate : ${source_default.cyan(s.drain_rate_per_min.toFixed(1))}/min` + source_default.dim(` (last ${s.drain_window_minutes}m, ${s.completed_in_window} completed)`));
+  console.log(`  ETA        : ${source_default.cyan(formatEta(s.eta_seconds))}`);
+  if (s.top_errors.length > 0) {
+    console.log(source_default.dim("-".repeat(48)));
+    console.log(source_default.bold("  Top errors:"));
+    for (const e of s.top_errors) {
+      console.log(`    ${source_default.red(String(e.count).padStart(4))}  ${e.reason}`);
+    }
+  }
+}
 function registerDocumentSyncCommands(program2) {
   const cmd = program2.command("document-sync").description("Manage durable document sync sources (Google Drive, etc.)");
   function getCtx() {
@@ -14185,17 +14243,17 @@ ${name}${tag}`));
       throw new CLIError("--source and --all are mutually exclusive", 4 /* Validation */);
     }
     const params = { dry_run: String(dryRun) };
-    let sources;
+    let sources2;
     if (opts.all) {
       const all = await ctx.api.get("/api/admin/document-sync/sources", { params: { provider: "google_drive" } });
-      sources = all;
+      sources2 = all;
     } else {
-      sources = [
+      sources2 = [
         { id: opts.source, name: opts.source, provider: "google_drive" }
       ];
     }
     const results = [];
-    for (const src of sources) {
+    for (const src of sources2) {
       const summary = await ctx.api.post(`/api/admin/document-sync/sources/${encodeURIComponent(src.id)}/reconcile-tree`, undefined, { params });
       results.push(summary);
       if (!isJson())
@@ -14210,6 +14268,88 @@ ${name}${tag}`));
 No google_drive sources found.`));
     }
   });
+  const sources = cmd.command("sources").description("Create, list, and run document sync sources");
+  sources.command("list").description("List document sync sources for the tenant").option("--provider <name>", "Filter by provider (e.g. s3_compatible_folder)").action(async (opts) => {
+    const ctx = getCtx();
+    const params = {};
+    if (opts.provider)
+      params.provider = opts.provider;
+    const rows = await ctx.api.get("/api/admin/document-sync/sources", { params });
+    if (isJson()) {
+      console.log(JSON.stringify(rows, null, 2));
+      return;
+    }
+    if (rows.length === 0) {
+      console.log(source_default.dim("No document sync sources found."));
+      return;
+    }
+    for (const s of rows) {
+      console.log(`  ${source_default.cyan((s.provider ?? "?").padEnd(22))} ${s.name}  ` + source_default.dim(`(id=${s.id}, profile=${s.provider_profile ?? "-"}, ` + `mode=${s.mode ?? "-"}, status=${s.status ?? "-"})`));
+    }
+  });
+  sources.command("create").description("Create a document sync source. For s3_compatible_folder pass " + "--bucket (+ --endpoint-url for custom_s3) and a --connection holding " + "the S3 credentials.").requiredOption("--provider <name>", "Provider: s3_compatible_folder | google_drive").requiredOption("--name <name>", "Source name (unique per tenant)").requiredOption("--collection <id>", "Target collection id (objects ingest here)").option("--connection <id>", "Connection id holding the source credentials (required for a " + "customer-owned s3 bucket)").option("--profile <name>", "s3 profile: custom_s3 | cloudflare_r2").option("--bucket <name>", "s3 bucket name (s3_compatible_folder)").option("--endpoint-url <url>", "s3 endpoint URL (required for custom_s3 / a customer bucket)").option("--prefix <prefix>", "s3 key prefix to sync (optional)").option("--mode <mode>", `Sync mode: ${VALID_MODES.join(" | ")}`, "manual").action(async (opts) => {
+    if (!VALID_MODES.includes(opts.mode)) {
+      throw new CLIError(`--mode must be one of: ${VALID_MODES.join(", ")}`, 4 /* Validation */);
+    }
+    const body = {
+      provider: opts.provider,
+      name: opts.name,
+      target_collection_id: opts.collection,
+      mode: opts.mode
+    };
+    if (opts.connection)
+      body.connection_id = opts.connection;
+    if (opts.provider === "s3_compatible_folder") {
+      if (!opts.bucket) {
+        throw new CLIError("--bucket is required for s3_compatible_folder.", 4 /* Validation */);
+      }
+      const profile = opts.profile ?? "custom_s3";
+      if (profile === "custom_s3" && !opts.endpointUrl) {
+        throw new CLIError("--endpoint-url is required for the custom_s3 profile.", 4 /* Validation */);
+      }
+      if (opts.connection && !opts.endpointUrl) {
+        throw new CLIError("--endpoint-url is required for a customer-owned bucket source " + "(one with --connection).", 4 /* Validation */);
+      }
+      body.provider_profile = profile;
+      const root = { bucket: opts.bucket };
+      if (opts.endpointUrl)
+        root.endpoint_url = opts.endpointUrl;
+      if (opts.prefix)
+        root.prefix = opts.prefix;
+      body.root_locator = root;
+    }
+    const ctx = getCtx();
+    const resp = await ctx.api.post("/api/admin/document-sync/sources", body);
+    if (isJson()) {
+      console.log(JSON.stringify(resp, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Created ${opts.provider} source '${opts.name}' ` + `(id=${resp.id}, mode=${resp.mode ?? opts.mode}). ` + `Run it with: martha document-sync sources reconcile ${resp.id}`));
+  });
+  for (const op of ["run", "reconcile"]) {
+    sources.command(`${op} <source_id>`).description(op === "reconcile" ? "Reconcile a source (full diff: ingest new/changed, soft-delete gone)" : "Run a one-off sync for a source").action(async (sourceId) => {
+      const ctx = getCtx();
+      const resp = await ctx.api.post(`/api/admin/document-sync/sources/${encodeURIComponent(sourceId)}/${op}`, undefined);
+      if (isJson()) {
+        console.log(JSON.stringify(resp, null, 2));
+        return;
+      }
+      console.log(source_default.green(`Started ${op} for source ${sourceId} ` + `(workflow=${resp.workflow_id}, status=${resp.status})`));
+    });
+  }
+  sources.command("status <source_id>").description("Show ingestion progress for a source: counts by status, drain " + "rate, ETA, and top error reasons.").option("--window-minutes <n>", "Drain-rate window in minutes (1–1440)", "15").action(async (sourceId, opts) => {
+    const windowMinutes = Number.parseInt(opts.windowMinutes, 10);
+    if (!Number.isFinite(windowMinutes) || windowMinutes < 1 || windowMinutes > 1440) {
+      throw new CLIError("--window-minutes must be an integer between 1 and 1440.", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const summary = await ctx.api.get(`/api/admin/document-sync/sources/${encodeURIComponent(sourceId)}/status`, { params: { window_minutes: String(windowMinutes) } });
+    if (isJson()) {
+      console.log(JSON.stringify(summary, null, 2));
+      return;
+    }
+    printIngestionStatus(sourceId, summary);
+  });
 }
 
 // src/commands/approvals.ts
@@ -15278,8 +15418,8 @@ ${data.length} spec(s)`));
 Resources:
 `));
       for (const r of resources) {
-        const path6 = r.path || `/${r.name}`;
-        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path6}`));
+        const path5 = r.path || `/${r.name}`;
+        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path5}`));
       }
     }
     try {
@@ -15299,14 +15439,14 @@ Functions:
     console.log(source_default.dim(`
 Proxy: martha integrations proxy ${name} GET /<path>`));
   });
-  cmd.command("proxy <name> <method> <path>").description("Send a request through the plugin proxy").option("--data <json>", "JSON request body").option("--query <params>", "Query params as key=val&key=val").action(async (name, method, path6, opts) => {
+  cmd.command("proxy <name> <method> <path>").description("Send a request through the plugin proxy").option("--data <json>", "JSON request body").option("--query <params>", "Query params as key=val&key=val").action(async (name, method, path5, opts) => {
     const ctx = getCtx();
     const upperMethod = method.toUpperCase();
     const allowed = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
     if (!allowed.has(upperMethod)) {
       throw new CLIError(`Invalid method: ${method}`, 4 /* Validation */, "Allowed: GET, POST, PUT, PATCH, DELETE");
     }
-    const cleanPath = path6.startsWith("/") ? path6.slice(1) : path6;
+    const cleanPath = path5.startsWith("/") ? path5.slice(1) : path5;
     const proxyUrl = `/api/admin/plugins/${encodeURIComponent(name)}/${cleanPath}`;
     const params = {};
     if (opts.query) {
@@ -15406,7 +15546,7 @@ Connections`));
     }
     console.log();
   });
-  cmd.command("create").description("Create a connection. For service_account, --credential-value is the SA " + "JSON key (use '@path' to read a file or '-' for stdin) and --config " + `carries non-secret settings, e.g. '{"subject":"u@corp.com","scopes":["https://www.googleapis.com/auth/drive.readonly"]}'. ` + "OAuth2 connections must be created in the admin UI (browser consent).").requiredOption("--integration <name>", "Integration name (e.g. google_drive)").requiredOption("--name <name>", "Connection name (unique per integration)").option("--auth-type <type>", "Auth type: api_key | bearer | basic | service_account", "api_key").option("--credential-value <value>", "Secret material. For service_account: the SA JSON key. " + "Use '-' to read stdin, '@path' to read a file.").option("--config <json>", "Non-secret config JSON object (stored in Postgres, not Vault)").option("--scope <scope>", "Connection scope (tenant|client|system)", "tenant").option("--scope-ref <ref>", "Scope reference (required for client scope)").option("--not-default", "Do not mark as default for this integration").action(async (opts) => {
+  cmd.command("create").description("Create a connection. For service_account, --credential-value is the SA " + "JSON key (use '@path' to read a file or '-' for stdin) and --config " + `carries non-secret settings, e.g. '{"subject":"u@corp.com","scopes":["https://www.googleapis.com/auth/drive.readonly"]}'. ` + "OAuth2 connections must be created in the admin UI (browser consent).").requiredOption("--integration <name>", "Integration name (e.g. google_drive)").requiredOption("--name <name>", "Connection name (unique per integration)").option("--auth-type <type>", "Auth type: api_key | bearer | basic | service_account | aws_access_key " + `(s3: --credential-value '{"access_key_id":"…","secret_access_key":"…"}')`, "api_key").option("--credential-value <value>", "Secret material. For service_account: the SA JSON key. " + "Use '-' to read stdin, '@path' to read a file.").option("--config <json>", "Non-secret config JSON object (stored in Postgres, not Vault)").option("--scope <scope>", "Connection scope (tenant|client|system)", "tenant").option("--scope-ref <ref>", "Scope reference (required for client scope)").option("--not-default", "Do not mark as default for this integration").action(async (opts) => {
     if (opts.authType === "oauth2") {
       throw new CLIError("OAuth2 connections cannot be created from the CLI — they require " + "an interactive browser consent flow.", 4 /* Validation */, "Create OAuth2 connections in the admin UI under Integrations → Connections.");
     }
@@ -15518,8 +15658,8 @@ async function resolveCredentialValue(value) {
   if (value === "-")
     return readStdin();
   if (value.startsWith("@")) {
-    const fs9 = await import("node:fs/promises");
-    return (await fs9.readFile(value.slice(1), "utf-8")).trim();
+    const fs8 = await import("node:fs/promises");
+    return (await fs8.readFile(value.slice(1), "utf-8")).trim();
   }
   return value;
 }
@@ -15634,8 +15774,8 @@ Notification connections`));
     if (credentialValue === "-") {
       credentialValue = await readStdin2();
     } else if (credentialValue?.startsWith("@")) {
-      const fs9 = await import("node:fs/promises");
-      credentialValue = await fs9.readFile(credentialValue.slice(1), "utf-8");
+      const fs8 = await import("node:fs/promises");
+      credentialValue = await fs8.readFile(credentialValue.slice(1), "utf-8");
     }
     if (!credentialValue) {
       throw new Error("--credential-value is required (use '-' for stdin or '@path' for file).");
@@ -15685,11 +15825,11 @@ async function readStdin2() {
 
 // src/commands/messaging.ts
 init_errors();
-async function messagingFetch(baseUrl, path6, opts) {
-  if (/^(https?:)?\/\//i.test(path6)) {
+async function messagingFetch(baseUrl, path5, opts) {
+  if (/^(https?:)?\/\//i.test(path5)) {
     throw new CLIError("Absolute URL paths are not allowed", 1 /* Error */);
   }
-  const url = new URL(path6, baseUrl);
+  const url = new URL(path5, baseUrl);
   const headers = {
     "Content-Type": "application/json"
   };
@@ -16979,7 +17119,7 @@ ${models.length} models`));
 }
 
 // src/commands/wiki.ts
-import fs9 from "node:fs";
+import fs8 from "node:fs";
 init_errors();
 function registerWikiCommands(program2) {
   const cmd = program2.command("wiki").description("Manage tenant wiki pages, settings, schema, recompile (#245 D5.4)");
@@ -17026,14 +17166,14 @@ function registerWikiCommands(program2) {
     console.log(source_default.dim(`
 ${pages.length} pages`));
   });
-  cmd.command("get <path>").description("Fetch the raw markdown body of a wiki page").option("--out <file>", "Write body to file instead of stdout").action(async (path6, opts) => {
+  cmd.command("get <path>").description("Fetch the raw markdown body of a wiki page").option("--out <file>", "Write body to file instead of stdout").action(async (path5, opts) => {
     const ctx = getCtx();
-    const safe = path6.split("/").map(encodeURIComponent).join("/");
+    const safe = path5.split("/").map(encodeURIComponent).join("/");
     const resp = await ctx.api.getRaw(`/api/wiki/pages/${safe}`, {
       headers: { Accept: "text/markdown,*/*" }
     });
     if (resp.status === 404) {
-      throw new CLIError(`page not found: ${path6}`, 3 /* NotFound */);
+      throw new CLIError(`page not found: ${path5}`, 3 /* NotFound */);
     }
     if (!resp.ok) {
       const detail = await resp.text();
@@ -17041,16 +17181,16 @@ ${pages.length} pages`));
     }
     const body = await resp.text();
     if (opts.out) {
-      fs9.writeFileSync(opts.out, body);
+      fs8.writeFileSync(opts.out, body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${body.length} bytes to ${opts.out}`));
       } else {
-        console.log(JSON.stringify({ path: path6, bytes: body.length, file: opts.out }));
+        console.log(JSON.stringify({ path: path5, bytes: body.length, file: opts.out }));
       }
       return;
     }
     if (isJson()) {
-      console.log(JSON.stringify({ path: path6, body, etag: resp.headers.get("ETag") }));
+      console.log(JSON.stringify({ path: path5, body, etag: resp.headers.get("ETag") }));
     } else {
       process.stdout.write(body);
     }
@@ -17145,10 +17285,10 @@ ${pages.length} pages`));
     }
     if (opts.compilePromptOverrideFile) {
       const file = String(opts.compilePromptOverrideFile);
-      if (!fs9.existsSync(file)) {
+      if (!fs8.existsSync(file)) {
         throw new CLIError(`override file not found: ${file}`, 3 /* NotFound */);
       }
-      const content = fs9.readFileSync(file, "utf8");
+      const content = fs8.readFileSync(file, "utf8");
       const bytes = Buffer.byteLength(content, "utf8");
       if (bytes > 16 * 1024) {
         throw new CLIError(`compile prompt override exceeds 16 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -17172,7 +17312,7 @@ ${pages.length} pages`));
     const ctx = getCtx();
     const resp = await ctx.api.get("/api/wiki/schema");
     if (opts.out) {
-      fs9.writeFileSync(opts.out, resp.body);
+      fs8.writeFileSync(opts.out, resp.body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${resp.body.length} bytes to ${opts.out}`));
       } else {
@@ -17188,10 +17328,10 @@ ${pages.length} pages`));
   });
   schemaCmd.command("set").description("Replace the tenant wiki schema with the contents of <file>").requiredOption("--file <file>", "Path to schema markdown file").action(async (opts) => {
     const ctx = getCtx();
-    if (!fs9.existsSync(opts.file)) {
+    if (!fs8.existsSync(opts.file)) {
       throw new CLIError(`schema file not found: ${opts.file}`, 3 /* NotFound */);
     }
-    const body = fs9.readFileSync(opts.file, "utf8");
+    const body = fs8.readFileSync(opts.file, "utf8");
     const bytes = Buffer.byteLength(body, "utf8");
     if (bytes > 64 * 1024) {
       throw new CLIError(`schema body exceeds 64 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -17229,7 +17369,7 @@ var PRESETS = {
   cloud: {
     name: "cloud",
     api_url: "https://martha.nomadriver.co",
-    keycloak_url: "https://keycloak.frank.nomadriver.co",
+    keycloak_url: "https://auth.nomadriver.co",
     keycloak_realm: "frank"
   },
   local: {
@@ -17244,7 +17384,7 @@ async function prompt2(rl, question, fallback) {
   return answer.trim() || fallback;
 }
 async function initCommand(opts) {
-  const presetKey = opts.preset ?? "local";
+  const presetKey = opts.preset ?? "cloud";
   const preset = PRESETS[presetKey];
   if (!preset) {
     throw new CLIError(`Unknown preset: ${presetKey}. Choose one of: ${Object.keys(PRESETS).join(", ")}.`, 4 /* Validation */);
@@ -17255,7 +17395,7 @@ async function initCommand(opts) {
     throw new CLIError(`Profile ${source_default.cyan(profileName)} already exists. Re-run with --force to overwrite, or pass --profile <name> to add a new one.`, 5 /* Conflict */);
   }
   const interactive = !opts.noInteractive && process.stdin.isTTY && !opts.apiUrl && !opts.keycloakUrl && !opts.keycloakRealm;
-  const profile = {
+  let profile = {
     api_url: opts.apiUrl ?? preset.api_url,
     keycloak_url: opts.keycloakUrl ?? preset.keycloak_url,
     keycloak_realm: opts.keycloakRealm ?? preset.keycloak_realm,
@@ -17287,7 +17427,6 @@ Martha CLI — first-run setup
   console.log();
   console.log(source_default.green(`Profile saved.
 `));
-  console.log(`  Preset:      ${source_default.cyan(preset.name)}`);
   console.log(`  Profile:     ${source_default.cyan(profileName)}`);
   console.log(`  API URL:     ${profile.api_url}`);
   console.log(`  Keycloak:    ${profile.keycloak_url}`);
@@ -17299,7 +17438,7 @@ Martha CLI — first-run setup
   console.log(source_default.dim("    martha doctor                        # verify setup"));
 }
 function registerInitCommand(program2) {
-  program2.command("init").description("Create or update a profile in ~/.martha/config.yaml").option("--preset <name>", "Preset: local or cloud", "local").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").action(async (opts) => {
+  program2.command("init").description("Create or update a profile in ~/.martha/config.yaml").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").action(async (opts) => {
     await initCommand(opts);
   });
 }
@@ -17547,19 +17686,19 @@ function registerDoctorCommand(program2) {
 
 // src/commands/skill.ts
 init_errors();
-import fs10 from "node:fs";
-import path6 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import fs9 from "node:fs";
+import path5 from "node:path";
+import { fileURLToPath } from "node:url";
 function locateSkill() {
-  const here = path6.dirname(fileURLToPath2(import.meta.url));
+  const here = path5.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path6.join(here, "skills", "martha-cli", "SKILL.md"),
-    path6.join(here, "..", "skills", "martha-cli", "SKILL.md"),
-    path6.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
-    path6.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
+    path5.join(here, "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
+    path5.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
   ];
   for (const p of candidates) {
-    if (fs10.existsSync(p))
+    if (fs9.existsSync(p))
       return p;
   }
   return null;
@@ -17569,7 +17708,7 @@ async function skillCommand() {
   if (!skillPath) {
     throw new CLIError("SKILL.md not found in the installed package. Reinstall via `npm i -g @aiaiai-pt/martha-cli` or `npx -y @aiaiai-pt/martha-cli@latest skill`.", 1 /* Error */);
   }
-  const body = fs10.readFileSync(skillPath, "utf-8");
+  const body = fs9.readFileSync(skillPath, "utf-8");
   process.stdout.write(body);
 }
 function registerSkillCommand(program2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -15,7 +15,7 @@ Martha has a few distinct primitives that get confused in everyday talk. This is
 |---|---|---|
 | **Tenant** | Opaque data isolation boundary (`tenant_id` string). All queries filter by this. Set from the JWT, never from request body. | Every entity is tenant-scoped. You don't pass it explicitly to the CLI — it comes from your token. |
 | **Client** | A chat-API consumer (web app, SMS sender, voice line). Has `keycloak_client_id`, `system_prompts`, allowlists. **Not a tenant.** | Use when you're configuring how a frontend or messaging channel talks to Martha. |
-| **Agent** | An `AgentDefinition` row: `system_prompt` + LLM config + loop config + tool grants. Cloud or external. | Cloud agents are run by Martha (Temporal). External agents are remote harnesses that authenticate and execute Martha tasks. |
+| **Agent** | An `AgentDefinition` row: prompt + LLM config + loop config + tool grants. Cloud or external. | Cloud agents are run by Martha (Temporal). External agents are remote harnesses that authenticate and execute Martha tasks. |
 | **Team** | A named group of agents with a routing strategy (`round_robin`, `manual`, `external`). | Use to spread work across many similar agents (e.g. 5 ork instances doing code review). |
 | **Task** | A unit of work with goal, priority, lifecycle (`open`/`claimed`/`running`/`completed`/`failed`/`cancelled`/`stale`/`poisoned`). Optionally linked to a tracker issue. | Use to queue async work for agents. Humans or agents can create them. |
 | **Function** | An HTTP endpoint or platform Python callable that an agent can invoke as a tool. Stored as `FunctionDefinition`. | Define once, grant to many agents. |
@@ -35,7 +35,7 @@ Everything below operates on these primitives. When in doubt, run `martha status
 | Flag | Purpose |
 |---|---|
 | `--json` | Machine-readable JSON output. **Always set this when piping to `jq` or parsing.** Without it, output is human-formatted and may include color codes. |
-| `--profile <name>` | Use a named profile from `~/.martha/config.yaml`. |
+| `--profile <name>` | Use a named profile from `~/.martha/profiles/`. Default profile is `default`. |
 | `--api-url <url>` | Override `MARTHA_API_URL`. Useful for hitting staging/prod from the same shell. |
 | `--verbose` | DEBUG-level logging on stderr. Shows HTTP requests, retry attempts, token expiry decisions. |
 | `--quiet` | Suppress informational output. Errors still print. |
@@ -47,28 +47,11 @@ Everything below operates on these primitives. When in doubt, run `martha status
 
 ## Authentication
 
-Install does not pre-provision a global profile. Configure one explicitly before
-running commands:
-
-```bash
-# Local development stack
-martha init --no-interactive --preset local
-
-# Customer, staging, or private-cloud tenant
-martha init --no-interactive --name acme \
-  --api-url https://martha.acme.example \
-  --keycloak-url https://auth.acme.example \
-  --keycloak-realm acme
-```
-
-Use `martha init --preset cloud` only when you intentionally want the hosted
-Martha cloud profile (`martha.nomadriver.co` + `keycloak.frank.nomadriver.co`).
-
 The CLI resolves credentials in this priority order. The first non-empty wins:
 
 1. `MARTHA_TOKEN` — raw JWT, bypasses all login flows. Highest priority.
 2. `MARTHA_CLIENT_ID` + `MARTHA_CLIENT_SECRET` — OAuth2 client credentials, auto-refreshes.
-3. Profile-stored token from prior `martha auth login` (cached under `~/.martha/` for the active profile).
+3. Profile-stored token from prior `martha auth login` (cached at `~/.martha/profiles/<name>.json`).
 4. Browser-based OIDC (interactive only, won't fire in non-TTY).
 
 ```bash
@@ -147,22 +130,9 @@ agent_type: cloud
 auth_method: service_account   # Slice 3B: provisions Keycloak SA on create
 system_prompt: "You write friendly morning briefings."
 llm_config: { provider: anthropic, model: claude-sonnet-4-5-20250929 }
-loop_config: { max_iterations: 5 }
+loop_config: { enabled: true, max_iterations: 5 }
 ```
 
-Agent field notes:
-
-- `system_prompt` is the durable instruction for the agent.
-- Grant an agent to a chat client with
-  `martha clients grant <client> agent <agent>` to make it callable as a tool
-  from that client.
-- `runs_as_chat` is an advanced top-level chat-takeover override, not normal
-  provisioning. Use it only when exactly one chat client should replace its own
-  `system_prompt`, `llm_config`, and tools with one agent.
-- `loop_config.enabled` is legacy compatibility. New YAML should not use it.
-- Workflow `llm` nodes use `config.prompt` for a one-step task prompt; that is
-  separate from an agent `system_prompt`.
-
 `--dry-run` prints what would change without writing. `--yes` skips the confirmation when applying to a non-empty tenant.
 
 ### Export (back up or migrate)
@@ -271,11 +241,11 @@ Default `execute_on` mapping: `llm` → `local`; `function` / `wait` / `transfor
 ```bash
 martha agents list [--inactive] [--limit 50]
 martha agents get <name>                  # Includes auth_method, status, llm_config, granted functions/workflows
-martha agents create --name <n> --model <m> --system-prompt "system prompt" \
+martha agents create --name <n> --model <m> --prompt "system prompt" \
     [--description "..."] [--temperature 0.7] [--max-tokens 4096] \
     [--type cloud|external] [--auth service-account|api-key] \
     [--tags code-review,python] [--local-tools filesystem,git]
-martha agents update <name> -f agent.yaml
+martha agents update <name> [--model <m>] [--prompt "..."] [--description "..."]
 martha agents delete <name> [--hard] [--yes]
 martha agents versions <name>
 martha agents rollback <name> <version>
@@ -865,7 +835,7 @@ martha teams add-member refactoring-team ork-1
 # Agent side
 export MARTHA_CLIENT_ID=<from above>
 export MARTHA_CLIENT_SECRET=<from above>
-export MARTHA_API_URL=https://martha.acme.example
+export MARTHA_API_URL=https://martha.nomadriver.co
 martha auth login --service-account
 martha tasks poll --json   # Should return open team-scoped tasks
 ```