@aiaiai-pt/martha-cli 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.4.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>
@@ -272,11 +302,13 @@ martha agents generate-key <agent>
 **Function grants:**
 
 ```bash
-martha agents add-function <agent> <function> [--set key=value]    # config_overrides
-martha agents remove-function <agent> <function>
+martha agents add-function <agent> <function> [--set key=value] [--collection <slug-or-id>]
+martha agents remove-function <agent> <function> [--collection <slug-or-id>]
 martha agents functions <agent>                                     # List granted functions
 ```
 
+`--collection` scopes the grant to one collection per the #372 PR2 cascade. Omit it to grant at the root (tenant-wide); pass it on `remove-function` to revoke just that scope. Server returns 400 if the function is collection-agnostic (e.g. `recall`).
+
 ---
 
 ## Tasks: queue + executor lifecycle
@@ -482,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
+```
 
-# 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}`):
@@ -579,9 +624,10 @@ Document collections are tenant-scoped containers that ingest files (PDF, DOCX,
 
 ```bash
 # Collections
-martha documents collections [--inactive] [--limit 50]
+martha documents collections [--inactive] [--limit 50] [--tree]      # --tree renders the parent/child hierarchy as ASCII (#372)
 martha documents collection <id>               # Stats, ingestion status, total size
-martha documents create-collection --name "My Docs" [--description "..."]
+martha documents create-collection --name "My Docs" [--description "..."] [--parent <slug-or-id>]
+martha documents move-collection <id> --parent <slug-or-id> | --root  # Atomic move; server rejects cycles
 
 # Document lifecycle
 martha documents upload <collection-id> <file> [--wait] [--follow]   # --follow streams ingestion progress
@@ -608,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.
@@ -653,11 +717,13 @@ martha clients update <name-or-id> [--name <n>] [--system-prompts '...']
 martha clients delete <name-or-id> [--force] [--yes]                  # --force drops sessions
 
 # Access grants — what definitions this client's sessions can use
-martha clients grant <client> function|workflow|agent <def-name> [--config key=value]
-martha clients revoke <client> function|workflow|agent <def-name>
+martha clients grant <client> function|workflow|agent <def-name> [--config key=value] [--collection <slug-or-id>]
+martha clients revoke <client> function|workflow|agent <def-name> [--collection <slug-or-id>]
 martha clients access <name-or-id>                                    # All grants for this client
 ```
 
+`--collection` is only valid on `function` grants (#372 PR2). The same UUID, slug, or name accepted by `documents move-collection` works here. Granting a scope on a collection-agnostic function (like `recall`) returns 400.
+
 ---
 
 ## Sessions + Chat
@@ -799,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
 ```
@@ -859,6 +925,35 @@ martha integrations specs --json | jq -r '.[] | select(.name == "linear") | .id'
 done
 ```
 
+### Collection hierarchy + scoped grants (#372)
+
+```bash
+# See the tree
+martha documents collections --tree
+
+# Build a hierarchy
+martha documents create-collection --name "Reports"
+martha documents create-collection --name "2026 Reports" --parent reports
+martha documents create-collection --name "Q1 2026" --parent 2026-reports
+
+# Reorganize
+martha documents move-collection q1-2026 --parent reports        # promote a level
+martha documents move-collection 2026-reports --root             # back to top-level
+
+# Scoped grants. Agent only sees docs in /Reports and descendants.
+martha agents add-function planner list_docs --collection reports
+martha agents add-function planner read_doc --collection reports
+
+# Most-specific ancestor wins: an additional grant on a child
+# collection overrides config_overrides for that subtree only.
+martha agents add-function planner list_docs --collection q1-2026 --set max_results=50
+
+# Revoke just one scope; the parent root grant (if any) survives.
+martha agents remove-function planner list_docs --collection q1-2026
+```
+
+`--collection` accepts UUID, slug, or name — same identifier the agent uses. Resolution mirrors the backend.
+
 ---
 
 ## Troubleshooting