@aiaiai-pt/martha-cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [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.
+
+### 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`.
+- Service-account Google Drive: `martha connections create --integration google_drive --auth-type service_account --credential-value @sa-key.json --config '{"subject":"...","scopes":[...]}'` reads enterprise Shared Drives without CASA (#407). The SA key shape (`type`, `client_email`) is validated before submit; `--credential-value` accepts `@file` / `-` (stdin) / literal.
+- **SA key rotation** (#407 key-rotation story): `martha connections update <id> --credential-value @new-sa.json` rotates the key in Vault in place and drops the cached SA token so the new key takes effect immediately (no ~1h staleness window).
+- OAuth2 connections are rejected with a clear error (they need interactive browser consent — use the admin UI).
+
+### Added — #372 PR5 inbound Drive folder sync
+- `document-sync reconcile-tree --source <id> | --all [--dry-run]` — backfills the collection tree from a Google Drive source's folder hierarchy. Stamps `drive_folder_id` on existing collections matching `(parent, name)` and creates sub-collections for unmapped Drive folders. Runs server-side against the source's live OAuth token; idempotent on re-run. `--dry-run` previews link/create/skip counts without writing.
+
 ## [0.5.0] — 2026-05-20
 
 ### Added — #372 PR4 collection-hierarchy CLI parity
@@ -17,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 + auth.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 + keycloak.frank.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.2.0 agents list --json
+npx -y @aiaiai-pt/martha-cli@0.5.1 agents list --json
 ```
 
 ### Install globally
@@ -31,9 +31,12 @@ Requires Node.js >= 22.
 
 ```bash
 # 1. Configure a profile — writes ~/.martha/config.yaml
-martha init                       # interactive (defaults to cloud preset)
-martha init --preset local        # localhost dev stack
-martha init --no-interactive --name staging --api-url https://...   # scripted
+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
 
 # 2. Authenticate
 martha auth login                 # browser flow (PKCE)
@@ -56,15 +59,19 @@ Full command reference: `martha --help` (or any subcommand `--help`).
 Profiles live at `~/.martha/config.yaml`. Each profile defines:
 
 ```yaml
-current_profile: default
+current_profile: local
 profiles:
-  default:
-    api_url: https://martha.nomadriver.co
-    keycloak_url: https://auth.nomadriver.co
+  local:
+    api_url: http://localhost:8080
+    keycloak_url: http://localhost:8180
     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
@@ -102,12 +109,32 @@ 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.3.0 ...
+npx -y @aiaiai-pt/martha-cli@0.5.1 ...
 ```
 
 `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,43 +5,25 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-function __accessProp(key) {
-  return this[key];
-}
-var __toESMCache_node;
-var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
-  var canCache = mod != null && typeof mod === "object";
-  if (canCache) {
-    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
-    var cached = cache.get(mod);
-    if (cached)
-      return cached;
-  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
+        get: () => mod[key],
         enumerable: true
       });
-  if (canCache)
-    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __returnValue = (v) => v;
-function __exportSetter(name, newValue) {
-  this[name] = __returnValue.bind(null, newValue);
-}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: __exportSetter.bind(all, name)
+      set: (newValue) => all[name] = () => newValue
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1019,7 +1001,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          }
+          } else {}
         };
       }
       return this;
@@ -11043,7 +11025,31 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.3.0";
+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();
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11105,7 +11111,8 @@ function printSessionTable(sessions) {
     { header: "LAST ACTIVE", accessor: (r) => r.active },
     { header: "CLIENT", accessor: (r) => r.client }
   ];
-  const stripAnsi = (s) => s.replace(/\x1B\[[0-9;]*m/g, "");
+  const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+  const stripAnsi = (s) => s.replace(ansiPattern, "");
   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));
@@ -11879,7 +11886,7 @@ function registerConfigCommand(program2) {
       config.current_profile = name;
     }
     saveConfig(config);
-    if (!!program2.opts().json) {
+    if (program2.opts().json) {
       console.log(JSON.stringify({
         name,
         profile,
@@ -11923,7 +11930,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;
     }
@@ -11932,8 +11939,8 @@ function registerConfigCommand(program2) {
 }
 
 // src/commands/definitions-apply.ts
-import fs5 from "node:fs";
-import path4 from "node:path";
+import fs6 from "node:fs";
+import path5 from "node:path";
 init_dist();
 init_errors();
 var VALID_KINDS = new Set(["Function", "Workflow", "Agent"]);
@@ -11968,20 +11975,20 @@ var SERVER_GENERATED_FIELDS = new Set([
 ]);
 var AGENT_MANAGED_FIELDS = new Set(["functions", "workflows"]);
 function loadDefinitions(inputPath) {
-  const resolved = path4.resolve(inputPath);
-  if (!fs5.existsSync(resolved)) {
+  const resolved = path5.resolve(inputPath);
+  if (!fs6.existsSync(resolved)) {
     throw new CLIError(`Path not found: ${inputPath}`, 1 /* Error */);
   }
-  const stat = fs5.statSync(resolved);
+  const stat = fs6.statSync(resolved);
   if (stat.isDirectory()) {
     return loadDirectory(resolved);
   }
   return loadFile(resolved);
 }
 function loadDirectory(dirPath) {
-  const entries = fs5.readdirSync(dirPath).sort();
+  const entries = fs6.readdirSync(dirPath).sort();
   const validExts = new Set([".yaml", ".yml", ".json"]);
-  const files = entries.filter((e) => validExts.has(path4.extname(e).toLowerCase())).map((e) => path4.join(dirPath, e));
+  const files = entries.filter((e) => validExts.has(path5.extname(e).toLowerCase())).map((e) => path5.join(dirPath, e));
   if (files.length === 0) {
     throw new CLIError(`No YAML or JSON files found in ${dirPath}`, 4 /* Validation */);
   }
@@ -11992,8 +11999,8 @@ function loadDirectory(dirPath) {
   return results;
 }
 function loadFile(filePath) {
-  const content = fs5.readFileSync(filePath, "utf-8");
-  const ext = path4.extname(filePath).toLowerCase();
+  const content = fs6.readFileSync(filePath, "utf-8");
+  const ext = path5.extname(filePath).toLowerCase();
   if (ext === ".json") {
     const parsed = parseJsonFile(content, filePath);
     return [toLocalDefinition(parsed, filePath)];
@@ -12415,7 +12422,7 @@ Examples:
 }
 
 // src/commands/definitions-export.ts
-import fs6 from "node:fs";
+import fs7 from "node:fs";
 init_errors();
 async function exportDefinitions(ctx, opts, isJsonMode) {
   const params = {};
@@ -12431,7 +12438,7 @@ async function exportDefinitions(ctx, opts, isJsonMode) {
   const text = await res.text();
   if (opts.output) {
     try {
-      fs6.writeFileSync(opts.output, text);
+      fs7.writeFileSync(opts.output, text);
     } catch (err) {
       throw new CLIError(`Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`, 1 /* Error */);
     }
@@ -13029,6 +13036,7 @@ 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 },
@@ -13036,7 +13044,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(/\x1B\[[0-9;]*m/g, "")).join(", ") || "-"
+        raw: (r) => (outgoing.get(r.id) ?? []).map((t) => t.replace(ansiPattern, "")).join(", ") || "-"
       }
     ];
     const widths = cols.map((col) => Math.max(col.header.length, ...rows.map((r) => col.raw(r).length)));
@@ -13154,8 +13162,8 @@ function registerProjectionCommands(parentCmd, getCtx, isJson) {
       } catch {}
     }
     if (opts.output) {
-      const fs7 = await import("node:fs/promises");
-      await fs7.writeFile(opts.output, toWrite, "utf-8");
+      const fs8 = await import("node:fs/promises");
+      await fs8.writeFile(opts.output, toWrite, "utf-8");
       if (!isJson()) {
         console.error(source_default.dim(`Wrote ${format} projection of '${name}' to ${opts.output}`));
       }
@@ -13318,16 +13326,20 @@ 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("--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");
+    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");
   },
   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;
-    if (opts.prompt)
-      body.system_prompt = opts.prompt;
+    const systemPrompt = opts.systemPrompt ?? opts.prompt;
+    if (systemPrompt)
+      body.system_prompt = systemPrompt;
     if (opts.type)
       body.agent_type = opts.type;
     if (opts.model)
@@ -13519,7 +13531,7 @@ Usage:
 };
 
 // src/commands/documents.ts
-import fs7 from "node:fs";
+import fs8 from "node:fs";
 init_errors();
 var TERMINAL_STATUSES2 = new Set(["ready", "error"]);
 var SPINNER_FRAMES2 = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -13820,7 +13832,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 (!fs7.existsSync(filePath)) {
+    if (!fs8.existsSync(filePath)) {
       throw new CLIError(`File not found: ${filePath}`, 4 /* Validation */);
     }
     const result = await ctx.api.upload(`/api/admin/collections/${encodeURIComponent(collectionId)}/documents`, filePath);
@@ -14137,6 +14149,69 @@ ${source_default.bold(`Sources (${result.sources.length} chunks):`)}`);
   });
 }
 
+// src/commands/document-sync.ts
+init_errors();
+function registerDocumentSyncCommands(program2) {
+  const cmd = program2.command("document-sync").description("Manage durable document sync sources (Google Drive, etc.)");
+  function getCtx() {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl)
+      ctx.profile.api_url = program2.opts().apiUrl;
+    return ctx;
+  }
+  function isJson() {
+    return !!program2.opts().json;
+  }
+  function printSummary(name, s) {
+    const tag = s.dry_run ? source_default.yellow(" (dry-run)") : "";
+    console.log(source_default.bold(`
+${name}${tag}`));
+    console.log(source_default.dim("-".repeat(40)));
+    console.log(`  Folders walked : ${s.folders_walked}`);
+    console.log(`  Linked         : ${source_default.cyan(String(s.linked))}`);
+    console.log(`  Created        : ${source_default.green(String(s.created))}`);
+    console.log(`  Skipped        : ${source_default.dim(String(s.skipped))}`);
+  }
+  cmd.command("reconcile-tree").description("Walk a Google Drive source's folder tree and mirror it into the " + "collection hierarchy (stamps drive_folder_id, creates sub-collections). " + "Idempotent.").option("--source <id>", "Reconcile a single sync source by id").option("--all", "Reconcile every google_drive source for the tenant").option("--dry-run", "Preview what would change without writing", false).action(async (opts) => {
+    const ctx = getCtx();
+    const dryRun = !!opts.dryRun;
+    if (!opts.source && !opts.all) {
+      throw new CLIError("Specify --source <id> or --all", 4 /* Validation */, "Use `martha document-sync reconcile-tree --source <id>` or `--all`.");
+    }
+    if (opts.source && opts.all) {
+      throw new CLIError("--source and --all are mutually exclusive", 4 /* Validation */);
+    }
+    const params = { dry_run: String(dryRun) };
+    let sources;
+    if (opts.all) {
+      const all = await ctx.api.get("/api/admin/document-sync/sources", { params: { provider: "google_drive" } });
+      sources = all;
+    } else {
+      sources = [
+        { id: opts.source, name: opts.source, provider: "google_drive" }
+      ];
+    }
+    const results = [];
+    for (const src of sources) {
+      const summary = await ctx.api.post(`/api/admin/document-sync/sources/${encodeURIComponent(src.id)}/reconcile-tree`, undefined, { params });
+      results.push(summary);
+      if (!isJson())
+        printSummary(src.name, summary);
+    }
+    if (isJson()) {
+      console.log(JSON.stringify({ dry_run: dryRun, results }, null, 2));
+      return;
+    }
+    if (results.length === 0) {
+      console.log(source_default.dim(`
+No google_drive sources found.`));
+    }
+  });
+}
+
 // src/commands/approvals.ts
 init_errors();
 var truncate = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
@@ -15203,8 +15278,8 @@ ${data.length} spec(s)`));
 Resources:
 `));
       for (const r of resources) {
-        const path5 = r.path || `/${r.name}`;
-        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path5}`));
+        const path6 = r.path || `/${r.name}`;
+        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path6}`));
       }
     }
     try {
@@ -15224,14 +15299,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, path5, 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, path6, 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 = path5.startsWith("/") ? path5.slice(1) : path5;
+    const cleanPath = path6.startsWith("/") ? path6.slice(1) : path6;
     const proxyUrl = `/api/admin/plugins/${encodeURIComponent(name)}/${cleanPath}`;
     const params = {};
     if (opts.query) {
@@ -15289,6 +15364,194 @@ function renderTable(columns, items, opts) {
   }
 }
 
+// src/commands/connections.ts
+init_errors();
+function registerConnectionCommands(program2) {
+  const cmd = program2.command("connections").description("Manage Vault-backed integration connections (credentials live in Vault)");
+  function getCtx() {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl)
+      ctx.profile.api_url = program2.opts().apiUrl;
+    return ctx;
+  }
+  function isJson() {
+    return !!program2.opts().json;
+  }
+  cmd.command("list").description("List connections for the current tenant").option("--integration <name>", "Filter by integration name").option("--scope <scope>", "Filter by scope (tenant|client|system)").action(async (opts) => {
+    const ctx = getCtx();
+    const query = new URLSearchParams;
+    if (opts.integration)
+      query.set("integration_name", opts.integration);
+    if (opts.scope)
+      query.set("scope", opts.scope);
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    const connections = await ctx.api.get(`/api/admin/connections${suffix}`);
+    if (isJson()) {
+      console.log(JSON.stringify(connections, null, 2));
+      return;
+    }
+    if (connections.length === 0) {
+      console.log(source_default.dim("No connections configured."));
+      return;
+    }
+    console.log(source_default.bold(`
+Connections`));
+    console.log(source_default.dim("-".repeat(60)));
+    for (const c of connections) {
+      const dflt = c.is_default ? source_default.green(" [default]") : "";
+      console.log(`  ${source_default.cyan(c.integration_name.padEnd(18))} ${c.name}${dflt}  ` + `${source_default.dim(c.auth_type)}  (${c.status})  ${source_default.dim(c.id)}`);
+    }
+    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) => {
+    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.");
+    }
+    const credentialValue = await resolveCredentialValue(opts.credentialValue);
+    if (!credentialValue) {
+      throw new CLIError("--credential-value is required (use '-' for stdin or '@path' for a file).", 4 /* Validation */);
+    }
+    if (opts.authType === "service_account") {
+      validateServiceAccountKey(credentialValue);
+    }
+    let config;
+    if (opts.config) {
+      let parsed;
+      try {
+        parsed = JSON.parse(opts.config);
+      } catch {
+        throw new CLIError("--config must be valid JSON.", 4 /* Validation */);
+      }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CLIError("--config must be a JSON object.", 4 /* Validation */);
+      }
+      config = parsed;
+    }
+    if (opts.scope === "client" && !opts.scopeRef) {
+      throw new CLIError("--scope-ref is required when --scope is 'client'.", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const resp = await ctx.api.post("/api/admin/connections", {
+      integration_name: opts.integration,
+      name: opts.name,
+      auth_type: opts.authType,
+      credential_value: credentialValue,
+      config,
+      scope: opts.scope,
+      scope_ref: opts.scope === "client" ? opts.scopeRef : undefined,
+      is_default: !opts.notDefault
+    });
+    if (isJson()) {
+      console.log(JSON.stringify(resp, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Created ${opts.integration} connection '${opts.name}' ` + `(id=${resp.id}, auth=${resp.auth_type}, status=${resp.status})`));
+  });
+  cmd.command("update <connection_id>").description("Update a connection — rotate the credential, rename, or change config/default. " + "For a service_account, --credential-value is the NEW SA JSON key; rotation " + "drops the cached SA token so the new key takes effect immediately.").option("--credential-value <value>", "New secret material. '@path' reads a file, '-' reads stdin.").option("--config <json>", "Replace the non-secret config JSON object.").option("--name <name>", "Rename the connection.").option("--default", "Mark as the default connection for this integration.").option("--not-default", "Unmark as default.").action(async (connectionId, opts) => {
+    const body = {};
+    if (opts.name)
+      body.name = opts.name;
+    if (opts.default)
+      body.is_default = true;
+    if (opts.notDefault)
+      body.is_default = false;
+    if (opts.config) {
+      let parsed;
+      try {
+        parsed = JSON.parse(opts.config);
+      } catch {
+        throw new CLIError("--config must be valid JSON.", 4 /* Validation */);
+      }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CLIError("--config must be a JSON object.", 4 /* Validation */);
+      }
+      body.config = parsed;
+    }
+    const credentialValue = await resolveCredentialValue(opts.credentialValue);
+    if (credentialValue)
+      body.credential_value = credentialValue;
+    if (Object.keys(body).length === 0) {
+      throw new CLIError("Nothing to update — pass --credential-value, --config, --name, or --default/--not-default.", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const resp = await ctx.api.put(`/api/admin/connections/${connectionId}`, body);
+    if (isJson()) {
+      console.log(JSON.stringify(resp, null, 2));
+      return;
+    }
+    const rotated = body.credential_value ? " (credential rotated)" : "";
+    console.log(source_default.green(`Updated connection ${resp.id}${rotated}`));
+  });
+  cmd.command("test <connection_id>").description("Test a connection's credentials against the integration").action(async (connectionId) => {
+    const ctx = getCtx();
+    const result = await ctx.api.post(`/api/admin/connections/${connectionId}/test`, {});
+    if (isJson()) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.ok) {
+      console.log(source_default.green("OK: connection test passed"));
+    } else {
+      console.log(source_default.red(`FAILED: ${result.error ?? "unknown error"}`));
+      process.exitCode = 1;
+    }
+  });
+  cmd.command("delete <connection_id>").description("Delete a connection (and its Vault credential). Requires --yes; " + "interactive prompts are intentionally NOT supported (CI would hang).").option("--yes", "Confirm deletion. Required.").action(async (connectionId, opts) => {
+    if (!opts.yes) {
+      throw new CLIError(`Pass --yes to confirm deletion of connection ${connectionId}.`, 4 /* Validation */, `Example: martha connections delete ${connectionId} --yes`);
+    }
+    const ctx = getCtx();
+    await ctx.api.del(`/api/admin/connections/${connectionId}`);
+    if (isJson()) {
+      console.log(JSON.stringify({ deleted: connectionId }, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Deleted connection ${connectionId}`));
+  });
+}
+async function resolveCredentialValue(value) {
+  if (!value)
+    return;
+  if (value === "-")
+    return readStdin();
+  if (value.startsWith("@")) {
+    const fs9 = await import("node:fs/promises");
+    return (await fs9.readFile(value.slice(1), "utf-8")).trim();
+  }
+  return value;
+}
+function validateServiceAccountKey(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CLIError("service_account --credential-value must be valid JSON (the SA key file).", 4 /* Validation */);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CLIError("service_account key must be a JSON object.", 4 /* Validation */);
+  }
+  const key = parsed;
+  if (key.type !== "service_account") {
+    throw new CLIError('This is not a service account key (expected "type": "service_account").', 4 /* Validation */, "Download the key from GCP → IAM → Service Accounts → Keys → JSON.");
+  }
+  if (typeof key.client_email !== "string" || !key.client_email.trim()) {
+    throw new CLIError("service_account key is missing client_email.", 4 /* Validation */);
+  }
+}
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new CLIError("--credential-value '-' requires piped stdin, but stdin is a terminal.", 4 /* Validation */, "Pipe the key in: `cat sa.json | martha connections create ... --credential-value -`, or use '@path' to read from a file.");
+  }
+  let out = "";
+  process.stdin.setEncoding("utf-8");
+  for await (const chunk of process.stdin)
+    out += chunk;
+  return out.trim();
+}
+
 // src/commands/notifications.ts
 var CHANNEL_IDS = new Set(["resend", "slack_webhook", "webhook"]);
 function registerNotificationCommands(program2) {
@@ -15369,10 +15632,10 @@ Notification connections`));
     }
     let credentialValue = opts.credentialValue;
     if (credentialValue === "-") {
-      credentialValue = await readStdin();
+      credentialValue = await readStdin2();
     } else if (credentialValue?.startsWith("@")) {
-      const fs8 = await import("node:fs/promises");
-      credentialValue = await fs8.readFile(credentialValue.slice(1), "utf-8");
+      const fs9 = await import("node:fs/promises");
+      credentialValue = await fs9.readFile(credentialValue.slice(1), "utf-8");
     }
     if (!credentialValue) {
       throw new Error("--credential-value is required (use '-' for stdin or '@path' for file).");
@@ -15409,7 +15672,7 @@ Notification connections`));
     console.log(source_default.green(`Deleted connection ${connectionId}`));
   });
 }
-async function readStdin() {
+async function readStdin2() {
   if (process.stdin.isTTY) {
     throw new Error("--credential-value '-' requires piped stdin, but stdin is a terminal. " + 'Either pipe JSON in: `echo \'{"...": "..."}\' | martha ...`, ' + "or use '@path' to read from a file.");
   }
@@ -15422,11 +15685,11 @@ async function readStdin() {
 
 // src/commands/messaging.ts
 init_errors();
-async function messagingFetch(baseUrl, path5, opts) {
-  if (/^(https?:)?\/\//i.test(path5)) {
+async function messagingFetch(baseUrl, path6, opts) {
+  if (/^(https?:)?\/\//i.test(path6)) {
     throw new CLIError("Absolute URL paths are not allowed", 1 /* Error */);
   }
-  const url = new URL(path5, baseUrl);
+  const url = new URL(path6, baseUrl);
   const headers = {
     "Content-Type": "application/json"
   };
@@ -16716,7 +16979,7 @@ ${models.length} models`));
 }
 
 // src/commands/wiki.ts
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 init_errors();
 function registerWikiCommands(program2) {
   const cmd = program2.command("wiki").description("Manage tenant wiki pages, settings, schema, recompile (#245 D5.4)");
@@ -16763,14 +17026,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 (path5, 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 (path6, opts) => {
     const ctx = getCtx();
-    const safe = path5.split("/").map(encodeURIComponent).join("/");
+    const safe = path6.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: ${path5}`, 3 /* NotFound */);
+      throw new CLIError(`page not found: ${path6}`, 3 /* NotFound */);
     }
     if (!resp.ok) {
       const detail = await resp.text();
@@ -16778,16 +17041,16 @@ ${pages.length} pages`));
     }
     const body = await resp.text();
     if (opts.out) {
-      fs8.writeFileSync(opts.out, body);
+      fs9.writeFileSync(opts.out, body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${body.length} bytes to ${opts.out}`));
       } else {
-        console.log(JSON.stringify({ path: path5, bytes: body.length, file: opts.out }));
+        console.log(JSON.stringify({ path: path6, bytes: body.length, file: opts.out }));
       }
       return;
     }
     if (isJson()) {
-      console.log(JSON.stringify({ path: path5, body, etag: resp.headers.get("ETag") }));
+      console.log(JSON.stringify({ path: path6, body, etag: resp.headers.get("ETag") }));
     } else {
       process.stdout.write(body);
     }
@@ -16882,10 +17145,10 @@ ${pages.length} pages`));
     }
     if (opts.compilePromptOverrideFile) {
       const file = String(opts.compilePromptOverrideFile);
-      if (!fs8.existsSync(file)) {
+      if (!fs9.existsSync(file)) {
         throw new CLIError(`override file not found: ${file}`, 3 /* NotFound */);
       }
-      const content = fs8.readFileSync(file, "utf8");
+      const content = fs9.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 */);
@@ -16909,7 +17172,7 @@ ${pages.length} pages`));
     const ctx = getCtx();
     const resp = await ctx.api.get("/api/wiki/schema");
     if (opts.out) {
-      fs8.writeFileSync(opts.out, resp.body);
+      fs9.writeFileSync(opts.out, resp.body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${resp.body.length} bytes to ${opts.out}`));
       } else {
@@ -16925,10 +17188,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 (!fs8.existsSync(opts.file)) {
+    if (!fs9.existsSync(opts.file)) {
       throw new CLIError(`schema file not found: ${opts.file}`, 3 /* NotFound */);
     }
-    const body = fs8.readFileSync(opts.file, "utf8");
+    const body = fs9.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 */);
@@ -16966,7 +17229,7 @@ var PRESETS = {
   cloud: {
     name: "cloud",
     api_url: "https://martha.nomadriver.co",
-    keycloak_url: "https://auth.nomadriver.co",
+    keycloak_url: "https://keycloak.frank.nomadriver.co",
     keycloak_realm: "frank"
   },
   local: {
@@ -16981,7 +17244,7 @@ async function prompt2(rl, question, fallback) {
   return answer.trim() || fallback;
 }
 async function initCommand(opts) {
-  const presetKey = opts.preset ?? "cloud";
+  const presetKey = opts.preset ?? "local";
   const preset = PRESETS[presetKey];
   if (!preset) {
     throw new CLIError(`Unknown preset: ${presetKey}. Choose one of: ${Object.keys(PRESETS).join(", ")}.`, 4 /* Validation */);
@@ -16992,7 +17255,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;
-  let profile = {
+  const profile = {
     api_url: opts.apiUrl ?? preset.api_url,
     keycloak_url: opts.keycloakUrl ?? preset.keycloak_url,
     keycloak_realm: opts.keycloakRealm ?? preset.keycloak_realm,
@@ -17024,6 +17287,7 @@ 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}`);
@@ -17035,7 +17299,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: 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) => {
+  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) => {
     await initCommand(opts);
   });
 }
@@ -17283,19 +17547,19 @@ function registerDoctorCommand(program2) {
 
 // src/commands/skill.ts
 init_errors();
-import fs9 from "node:fs";
-import path5 from "node:path";
-import { fileURLToPath } from "node:url";
+import fs10 from "node:fs";
+import path6 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function locateSkill() {
-  const here = path5.dirname(fileURLToPath(import.meta.url));
+  const here = path6.dirname(fileURLToPath2(import.meta.url));
   const candidates = [
-    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")
+    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")
   ];
   for (const p of candidates) {
-    if (fs9.existsSync(p))
+    if (fs10.existsSync(p))
       return p;
   }
   return null;
@@ -17305,7 +17569,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 = fs9.readFileSync(skillPath, "utf-8");
+  const body = fs10.readFileSync(skillPath, "utf-8");
   process.stdout.write(body);
 }
 function registerSkillCommand(program2) {
@@ -17364,11 +17628,13 @@ registerDefinitionCommands(program2, agentsConfig);
 registerDefinitionsApply(program2);
 registerDefinitionsExport(program2);
 registerDocumentCommands(program2);
+registerDocumentSyncCommands(program2);
 registerWikiCommands(program2);
 registerApprovalCommands(program2);
 registerTaskCommands(program2);
 registerTeamCommands(program2);
 registerIntegrationCommands(program2);
+registerConnectionCommands(program2);
 registerNotificationCommands(program2);
 registerMessagingCommands(program2);
 registerClientCommands(program2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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: 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: `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. |
 | **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/profiles/`. Default profile is `default`. |
+| `--profile <name>` | Use a named profile from `~/.martha/config.yaml`. |
 | `--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,11 +47,28 @@ 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 at `~/.martha/profiles/<name>.json`).
+3. Profile-stored token from prior `martha auth login` (cached under `~/.martha/` for the active profile).
 4. Browser-based OIDC (interactive only, won't fire in non-TTY).
 
 ```bash
@@ -130,9 +147,22 @@ 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: { enabled: true, max_iterations: 5 }
+loop_config: { 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)
@@ -241,11 +271,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> --prompt "system prompt" \
+martha agents create --name <n> --model <m> --system-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> [--model <m>] [--prompt "..."] [--description "..."]
+martha agents update <name> -f agent.yaml
 martha agents delete <name> [--hard] [--yes]
 martha agents versions <name>
 martha agents rollback <name> <version>
@@ -484,38 +514,51 @@ martha tasks poll --json
 
 A **Connection** is a stored credential record for an integration. Auth values live in HashiCorp Vault keyed by `(scope, scope_id, service_name)`. The DB only has metadata. Tracker connections include adapter-specific config (team_id, repository, project_id) stored as a flat dict in Vault — `resolve_connection_config()` is the single merge point for tracker adapter calls.
 
-The CLI doesn't yet have a top-level `connections` subcommand — manage them via the admin UI at `/settings` (Trackers tab) or via the API:
-
 ```bash
-# List connections (uses your token's tenant_id scope)
-curl -s -H "Authorization: Bearer $(martha auth token)" \
-  "$MARTHA_API_URL/api/admin/connections" | jq
+martha connections list [--integration <name>] [--scope tenant|client|system]
+martha connections create --integration <name> --name <name> --auth-type <type> \
+  --credential-value <value|@file|-> [--config '<json>'] \
+  [--scope tenant|client|system] [--scope-ref <ref>] [--not-default]
+martha connections update <connection-id> [--credential-value <value|@file|->] \
+  [--config '<json>'] [--name <name>] [--default|--not-default]
+martha connections test <connection-id>
+martha connections delete <connection-id> --yes
+```
+
+**Rotating a service-account key:** `martha connections update <id> --credential-value @new-sa.json`
+replaces the SA key in Vault in place (same connection id, sources stay attached)
+and drops the cached SA token so the new key takes effect immediately.
 
-# List available tracker adapters + their config_schema
-curl -s -H "Authorization: Bearer $(martha auth token)" \
-  "$MARTHA_API_URL/api/admin/trackers" | jq
+`--credential-value` accepts a literal, `@path` (read a file), or `-` (read stdin).
+`--config` is a non-secret JSON object stored in Postgres (never Vault).
+**OAuth2 connections cannot be created from the CLI** — they need an interactive
+browser consent flow; use the admin UI under Integrations → Connections.
 
-# Create a Linear connection (full config dict in JSON, stored as one Vault entry)
-curl -s -X POST -H "Authorization: Bearer $(martha auth token)" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "integration_name": "linear",
-    "name": "production",
-    "auth_type": "api_key",
-    "credential_value": "{\"api_key\":\"lin_api_xxx\",\"team_id\":\"uuid-here\"}",
-    "is_default": true
-  }' \
-  "$MARTHA_API_URL/api/admin/connections"
+```bash
+# Google Drive via service account (#407) — reads enterprise Shared Drives
+# without CASA. credential_value is the SA JSON key; config carries the
+# optional impersonation subject (domain-wide delegation) + scopes.
+martha connections create \
+  --integration google_drive --name "SOMENGIL Drive" \
+  --auth-type service_account \
+  --credential-value @/path/to/sa-key.json \
+  --config '{"subject":"owner@corp.com","scopes":["https://www.googleapis.com/auth/drive.readonly"]}'
+# Then add the SA's client_email as a member (Viewer) of the Shared Drive.
 
-# Test a connection (calls adapter.test_connection() with merged config)
-curl -s -X POST -H "Authorization: Bearer $(martha auth token)" \
-  "$MARTHA_API_URL/api/admin/connections/<connection-id>/test" | jq
+# Linear connection (full config dict in JSON, stored as one Vault entry)
+martha connections create --integration linear --name production \
+  --auth-type api_key \
+  --credential-value '{"api_key":"lin_api_xxx","team_id":"uuid-here"}'
 
-# Delete (also removes from Vault and deprovisions tracker triggers if applicable)
-curl -s -X DELETE -H "Authorization: Bearer $(martha auth token)" \
-  "$MARTHA_API_URL/api/admin/connections/<connection-id>"
+# Test a connection (calls the adapter's health check with merged config)
+martha connections test <connection-id>
 ```
 
+`martha connections create` mirrors `POST /api/admin/connections`. For
+service_account it validates the key shape (`type`, `client_email`) before
+submit. List available tracker adapters + their `config_schema` via
+`curl -s -H "Authorization: Bearer $(martha auth token)" "$MARTHA_API_URL/api/admin/trackers" | jq`.
+
 **Tracker connection auto-provisioning:** When you create a connection where `integration_name` matches a tracker (`linear`/`github`/`gitlab`), the backend automatically provisions:
 1. A `webhook_definition` (returns one-time `webhook_url` + `webhook_secret` in the create response)
 2. Three trigger definitions (managed by `tracker:{type}`):
@@ -611,6 +654,24 @@ A failed enrich step does NOT fail the document — it falls back to keyword-onl
 
 ---
 
+## Document Sync (durable Drive/folder sync)
+
+Durable sync sources mirror an external provider (Google Drive today) into Martha collections. Folder structure changes in Drive — move, rename, delete — propagate to the collection tree inbound (#372 PR5).
+
+```bash
+# Backfill / repair the collection tree from a Drive source's folder hierarchy.
+# Stamps drive_folder_id on existing collections matching (parent, name) and
+# creates sub-collections for unmapped Drive folders. Idempotent.
+martha document-sync reconcile-tree --source <source-id> [--dry-run]
+martha document-sync reconcile-tree --all [--dry-run]          # every google_drive source
+```
+
+`reconcile-tree` is the one-shot backfill that maps a source connected before folder-sync existed (or repairs drift). It runs server-side against the source's live OAuth token, so the source must be connected and validatable. `--dry-run` prints the would-link / would-create / skipped counts without writing. Re-running is safe — already-linked folders are skipped.
+
+Cross-source moves are rejected: a collection can't move between sync sources. Reorganize the folder in Drive directly and inbound sync mirrors it.
+
+---
+
 ## Approvals (human-in-the-loop)
 
 Approvals are pause-points inside workflows. The `approval_gate` workflow node creates an `ApprovalCase`; downstream nodes wait until a human resolves it.
@@ -804,7 +865,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.nomadriver.co
+export MARTHA_API_URL=https://martha.acme.example
 martha auth login --service-account
 martha tasks poll --json   # Should return open team-scoped tasks
 ```