@aiaiai-pt/martha-cli 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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]
+
+### 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

package/dist/index.js

@@ -13765,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)}`);
     }
@@ -14137,6 +14138,139 @@ ${source_default.bold(`Sources (${result.sources.length} chunks):`)}`);
   });
 }
 
+// src/commands/document-sync.ts
+init_errors();
+var VALID_MODES = ["polling", "evented", "manual"];
+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 sources2;
+    if (opts.all) {
+      const all = await ctx.api.get("/api/admin/document-sync/sources", { params: { provider: "google_drive" } });
+      sources2 = all;
+    } else {
+      sources2 = [
+        { id: opts.source, name: opts.source, provider: "google_drive" }
+      ];
+    }
+    const results = [];
+    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())
+        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.`));
+    }
+  });
+  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})`));
+    });
+  }
+}
+
 // src/commands/approvals.ts
 init_errors();
 var truncate = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
@@ -15289,6 +15423,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 | 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.");
+    }
+    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 fs8 = await import("node:fs/promises");
+    return (await fs8.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,7 +15691,7 @@ 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");
@@ -15409,7 +15731,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.");
   }
@@ -17364,11 +17686,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.6.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -484,38 +484,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
+```
 
-# List available tracker adapters + their config_schema
-curl -s -H "Authorization: Bearer $(martha auth token)" \
-  "$MARTHA_API_URL/api/admin/trackers" | jq
+**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.
 
-# 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"
+`--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.
+
+```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 +624,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.