@aiaiai-pt/martha-cli 0.2.0

package/skills/martha-cli/SKILL.md

@@ -0,0 +1,907 @@
+---
+name: martha-cli
+description: Complete reference for the Martha CLI. Use this whenever you need to manage Martha definitions (functions, workflows, agents), execute workflows, manage agent tasks, configure tracker integrations (Linear/GitHub/GitLab), upload documents for RAG, handle approvals, manage credentials in Vault, or interact with Martha's AI platform from the command line.
+---
+
+# Martha CLI Reference
+
+Martha is an AI workflow orchestration platform. Agents, workflows, and tasks run on a Temporal-backed engine. External agent harnesses (ork, Claude Code, CrewAI, Pydantic AI) interact through this CLI. This skill is the operational reference — assume you have shell access and never need `--help`.
+
+## Conceptual model
+
+Martha has a few distinct primitives that get confused in everyday talk. This is the precise meaning each one has in the platform:
+
+| Concept | What it is | When to use |
+|---|---|---|
+| **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. |
+| **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. |
+| **Workflow** | A graph of nodes (LLM, function, choice, parallel, agent_loop, etc.) executed by Temporal. | Multi-step pipelines that an agent or human triggers. |
+| **Connection** | A stored credential for an integration (tracker, OpenAPI service). Auth values live in Vault, not in DB. | One per (tenant, integration_name, name). Used by tracker adapters and HTTP function execution. |
+| **Tracker** | Built-in adapter for an external issue tracker (`linear`, `github`, `gitlab`). Bidirectional sync with Martha tasks. | Configure once per tenant, then tasks can carry `external_ref` + `tracker_type`. |
+| **Trigger** | Event-driven workflow/function dispatch. Listens for `event_type`, optionally filters, then fires a target. | Wire `task.completed` → notify, or `webhook.received` → sync inbound. |
+| **Webhook** | Inbound endpoint with per-webhook HMAC secret. Emits `webhook.received` events that triggers consume. | Receive callbacks from external services (trackers, payment processors, etc.). |
+| **Approval** | Human-in-the-loop pause point inside a workflow. | Use the `approval_gate` workflow node when you need a human OK before continuing. |
+
+Everything below operates on these primitives. When in doubt, run `martha status` to confirm tenant + auth before issuing commands.
+
+---
+
+## Global Options (every command)
+
+| 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`. |
+| `--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. |
+| `--yes` | Skip confirmation prompts. Required in non-TTY contexts (CI, agents). **The CLI does NOT silently cancel on no-TTY** — it errors with `use --yes`. |
+
+**Exit codes:** `0` success · `1` generic error · `2` auth failure · `3` not found · `4` validation · `5` conflict (409)
+
+---
+
+## Authentication
+
+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`).
+4. Browser-based OIDC (interactive only, won't fire in non-TTY).
+
+```bash
+# Headless login (humans, scripts)
+martha auth login --username admin --password admin123
+
+# Service account (agents, CI)
+export MARTHA_CLIENT_ID="martha-agent-<uuid>"
+export MARTHA_CLIENT_SECRET="..."
+martha auth login --service-account
+
+# Browser flow (local dev)
+martha auth login
+
+# Inspect current state
+martha auth status                # profile, user, tenant, expiry, roles
+martha auth token                 # raw JWT to stdout (for piping into curl)
+martha auth logout
+```
+
+**Token lifecycle:** Service-account tokens auto-refresh ~30s before expiry. Human tokens expire after ~5min and require re-login (or use `MARTHA_TOKEN` for long-running scripts).
+
+**Troubleshooting:**
+- `2 auth failure` on first call → token missing or expired. Run `martha auth status` to confirm, then re-login.
+- `403 forbidden` → authenticated but lacking the required role. Most admin endpoints need `admin` realm role; executor endpoints accept any authenticated user.
+- `401 unauthorized` despite valid token → check `MARTHA_API_URL` matches the Keycloak realm the token was issued for.
+
+---
+
+## Definitions: functions, workflows, agents
+
+Definitions are the durable building blocks. They're versioned (every update creates a `DefinitionVersion` row), tenant-scoped, and rollback-able.
+
+### Declarative Apply (preferred for IaC-style workflows)
+
+```bash
+martha definitions apply -f definitions.yaml [--dry-run] [--yes]
+```
+
+Reads YAML or JSON. Multi-document files (separated by `---`) are processed in order. The CLI **never deletes** — to remove a definition, use the per-kind `delete` command.
+
+```yaml
+kind: Function
+name: get-weather
+description: Fetches current weather by city name
+definition:
+  endpoint: https://api.weather.com/current
+  http_method: GET
+  parameters:
+    city:
+      type: string
+      required: true
+      location: query
+  auth:
+    scheme: bearer
+    credential_source: weather_api
+---
+kind: Workflow
+name: morning-briefing
+description: Get weather + headlines, summarize
+definition:
+  nodes:
+    - id: weather
+      type: function
+      config: { function_name: get-weather, inputs: { city: "{{user.city}}" } }
+    - id: summarize
+      type: llm
+      config: { prompt: "Summarize for a morning briefing: {{steps.weather.output}}" }
+  edges:
+    - { source: weather, target: summarize }
+---
+kind: Agent
+name: briefing-agent
+description: Sends a daily morning briefing
+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 }
+```
+
+`--dry-run` prints what would change without writing. `--yes` skips the confirmation when applying to a non-empty tenant.
+
+### Export (back up or migrate)
+
+```bash
+martha definitions export [--format yaml|json] [--output FILE] [--inactive]
+martha definitions export --functions-only
+martha definitions export --workflows-only
+```
+
+### Stats
+
+```bash
+martha definitions stats          # Counts by kind and source (manual/openapi/plugin)
+```
+
+### Functions CRUD
+
+```bash
+martha functions list [--source manual|openapi|platform|plugin] [--tag TAG] [--inactive] [--limit 50]
+martha functions get <name>                                    # Full definition + auth + extra_headers
+martha functions create -f definition.yaml
+martha functions update <name> -f definition.yaml              # Bumps version
+martha functions delete <name> [--hard] [--yes]                # Soft delete by default; --hard purges
+martha functions versions <name>                               # Version history with timestamps
+martha functions rollback <name> <version>                     # Restore prior version (creates new version)
+martha functions export [--format yaml|json] [--output FILE]
+```
+
+Function `auth` field is the most error-prone part — see the [Function authentication patterns](#function-authentication-patterns) section below.
+
+### Workflows CRUD + Execution
+
+```bash
+martha workflows list [--inactive] [--limit 50]
+martha workflows get <name>                                    # Full graph + variables + format_version
+martha workflows create -f definition.yaml
+martha workflows update <name> -f definition.yaml
+martha workflows delete <name> [--hard] [--yes]
+martha workflows versions <name>
+martha workflows rollback <name> <version>
+martha workflows export [--format yaml|json] [--output FILE]
+```
+
+**Execution:**
+
+```bash
+# Fire and forget
+martha workflows execute <name> --inputs '{"key": "value"}'
+
+# Wait for completion (blocks up to --timeout seconds, default 300)
+martha workflows execute <name> --inputs '{"key": "value"}' --wait
+
+# Wait + stream node-by-node progress to stdout
+martha workflows execute <name> --inputs '{"key": "value"}' --wait --follow
+
+# Inspect a running execution
+martha workflows execution <execution-id>                      # Snapshot
+martha workflows execution <execution-id> --follow             # Live stream
+
+# List recent executions
+martha workflows executions [--status running|completed|failed] [--workflow <name>] [--limit 20]
+
+# Cancel a running execution (signals Temporal workflow)
+martha workflows cancel <execution-id>
+```
+
+**Inspection (don't memorize, query the system):**
+
+```bash
+martha workflows inputs <name>            # Inputs the workflow expects, with types
+martha workflows nodes <name>             # All nodes + edges, useful for debugging
+martha workflows node-types               # Available node types you can use
+martha workflows node-type <type>         # Schema for a specific node type (e.g. agent_loop)
+```
+
+**Project a workflow as portable self-guidance (Phase 2 / Slice 2B):**
+
+When an external harness (ork, Claude Code, CrewAI, Pydantic AI) wants to *use* a Martha workflow as a recipe — without Martha being in the loop at execution time — project it to a portable format:
+
+```bash
+# JSON plan: topologically ordered nodes + execute_on hints + graph structure
+martha workflows project <name>                        # default --format=plan
+martha workflows project <name> --format=plan -o plan.json
+
+# Markdown run-book: numbered steps with prompts inlined
+martha workflows project <name> --format=skill         # writes to stdout
+martha workflows project <name> --format=skill -o skill.md
+```
+
+**Plan format** is for programmatic agents. Each node carries `id`, `type`, `execute_on` (hint only: `martha` = a server-side tool like a function; `local` = the agent runs it), `depends_on`, and — when known — `input_schema` / `output_schema`. Structural `start`/`end` nodes are filtered out; `edges` is preserved. No CLI commands are emitted — the projection is guidance, not a script.
+
+**Skill format** is Markdown, suitable for embedding in an LLM prompt or dropping into a Claude Code / ork skill directory. Numbered steps with LLM prompts inlined for `local` steps and Martha function names surfaced for `martha` steps.
+
+**How to execute a projected workflow:** the agent chooses. Common options:
+- **Run it yourself end-to-end**: use your own LLM for `local` steps; for `martha` steps, either call the underlying function as a tool (`martha functions call <name> --args …`) or implement an equivalent in your runtime.
+- **Delegate the whole thing**: skip the projection entirely and `martha workflows execute <name> --inputs '…'` — Martha runs it cloud-side and you just read the outcome.
+- **Mix and match**: follow the skill for structure but call Martha functions where useful.
+
+Default `execute_on` mapping: `llm` → `local`; `function` / `wait` / `transform` / `agent_loop` / `choice` → `martha`. Override per node by setting `execute_on` in the node config.
+
+> **Naming note:** the spec called this command `workflows export <name>`, but `workflows export` was already taken by the bulk-YAML export alias. The Phase 2 command is `project` instead.
+
+### Agents CRUD + Provisioning + Access
+
+```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" \
+    [--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 delete <name> [--hard] [--yes]
+martha agents versions <name>
+martha agents rollback <name> <version>
+```
+
+**Auth provisioning (Slice 3B — unified):**
+
+```bash
+# Provision auth for the first time, switch methods, or rotate credentials
+martha agents provision-auth <agent> --method service-account
+martha agents provision-auth <agent> --method api-key
+
+# Backward-compat alias for provision-auth --method=api-key
+martha agents generate-key <agent>
+```
+
+`provision-auth` shows credentials **once** — copy them immediately. Output is `Cache-Control: no-store` and never logs the secret.
+
+| Method | Returns | Use when |
+|---|---|---|
+| `service-account` | `client_id` + `client_secret` (export to `MARTHA_CLIENT_ID`/`MARTHA_CLIENT_SECRET`) | Long-running agents that need token refresh. Recommended. |
+| `api-key` | Single `martha_ak_...` token (export to `MARTHA_TOKEN`) | One-shot scripts, CI jobs, debugging. |
+
+**Function grants:**
+
+```bash
+martha agents add-function <agent> <function> [--set key=value]    # config_overrides
+martha agents remove-function <agent> <function>
+martha agents functions <agent>                                     # List granted functions
+```
+
+---
+
+## Tasks: queue + executor lifecycle
+
+Tasks are the unit of async work. Two flows operate on the same `tasks` table from different angles:
+
+- **Admin flow:** humans (or agents acting as humans) create, monitor, cancel tasks
+- **Executor flow:** external agents poll, claim, heartbeat, complete
+
+### Admin commands
+
+```bash
+martha tasks list [--status open|claimed|running|completed|failed|cancelled|stale|poisoned] \
+    [--agent <id>] [--priority low|medium|high|urgent] [--search QUERY] [--limit 50]
+martha tasks stats                          # Counts per status
+
+martha tasks create --agent <agent-id> --goal "instruction text" \
+    [--title "label"] [--priority medium] [--context '{"key":"val"}'] \
+    [--team <team-id>] [--assigned-agent <agent-id>] [--sticky] \
+    [--lease-timeout 600] [--max-retries 3]
+
+martha tasks view <id>                      # Full task: outcome, error, executor, lease, tracker info
+martha tasks cancel <id>                    # Transitions to cancelled; signals Temporal workflow if running
+```
+
+**Team routing:**
+- Without `--team`/`--assigned-agent` → task lives in tenant queue, any agent can claim
+- `--team <id>` → routes via team's `routing_strategy` (round_robin assigns to next active member at create time)
+- `--assigned-agent <id>` → pinned to that agent; only it can claim
+- `--sticky` → assignment survives the agent going offline (default: re-route on offline)
+
+**Tracker linkage (Phase 4):**
+Tasks created from a tracker webhook automatically get `external_ref` (e.g. `ENG-423`) and `tracker_type` (`linear`/`github`/`gitlab`). On status changes, the auto-provisioned trigger pushes back to the tracker. To create a tracker-linked task manually, use the API directly — there's no `--tracker-ref` flag yet.
+
+### Executor commands (the agent side)
+
+```bash
+# 1a. Discover available work — ordered by priority then age (polling)
+martha tasks poll [--agent <id>] [--limit 10]
+
+# 1b. Long-poll via SSE — connection stays open, prints one event per assignment
+#     (Phase 2 / Slice 2A). Survives reconnect via Last-Event-ID; sends
+#     ": keepalive" comment heartbeats every ~5s so intermediaries don't drop.
+martha tasks watch --team <name-or-id> [--json] [--max-reconnects N]
+
+# 2. Atomic claim — sets executor_id from your auth context, starts lease
+martha tasks claim <id> [--lease-timeout 300]
+
+# 3. Heartbeat — renew lease, optionally save checkpoint
+martha tasks heartbeat <id>
+martha tasks heartbeat <id> --checkpoint '{"step": 3, "progress": 0.75}'
+
+# 4. Report completion
+martha tasks complete <id> --outcome '{"result": "done", "files_changed": ["src/foo.py"]}'
+```
+
+**Claim lifecycle:** `open` → `claimed` (after `claim`) → `running` (when work starts; auto-set on first heartbeat after claim) → `completed`
+
+**Lease semantics:**
+- Default lease: 300s (5min). Override with `--lease-timeout` on claim.
+- Heartbeat **before `lease_expires_at`** or the reaper marks task `stale` and re-queues.
+- Recommended cadence: heartbeat every 30–60s.
+- Heartbeats from a non-executor return 403. Heartbeats after lease expiry return 409.
+
+**Checkpoint resume:**
+If `martha tasks claim <id>` returns a task with `retry_count > 0` and a `last_checkpoint`, a previous executor failed mid-work. Resume from the checkpoint instead of starting over. Inspect:
+```bash
+martha tasks view <id> --json | jq '.last_checkpoint, .retry_count'
+```
+
+**Error handling cheat sheet:**
+
+| Code | Meaning | Action |
+|---|---|---|
+| `409 Conflict` on claim | Task already claimed | Skip and try the next polled task |
+| `409 Conflict` on heartbeat | Lease expired | Stop work, do NOT complete (another agent will pick it up) |
+| `403 Forbidden` on heartbeat | You're not the executor | Stop work |
+| `404 Not Found` | Task was hard-deleted | Stop work |
+| `423 Locked` | Concurrent claim attempt in flight | Retry once after 100ms |
+
+### Standard executor loop
+
+Two flavours — pick polling for simplicity or `watch` for low-latency assignment:
+
+**Polling (works on any team / unassigned pool):**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+export MARTHA_TOKEN="${MARTHA_TOKEN:?need token}"
+
+while true; do
+  TASK_JSON=$(martha tasks poll --json --limit 1 | jq -c '.[0] // empty')
+  if [ -z "$TASK_JSON" ]; then
+    sleep 10
+    continue
+  fi
+
+  TASK_ID=$(echo "$TASK_JSON" | jq -r '.id')
+  GOAL=$(echo "$TASK_JSON" | jq -r '.goal')
+
+  # Atomic claim — bail if someone else got it
+  if ! martha tasks claim "$TASK_ID" --json >/dev/null 2>&1; then
+    continue
+  fi
+
+  # Background heartbeat every 30s for the duration
+  ( while sleep 30; do martha tasks heartbeat "$TASK_ID" --json >/dev/null || break; done ) &
+  HB_PID=$!
+
+  # Do the work — replace with your agent's actual logic
+  RESULT=$(echo "Working on: $GOAL" | your-agent-here)
+
+  kill $HB_PID 2>/dev/null || true
+  martha tasks complete "$TASK_ID" --json --outcome "$(jq -n --arg r "$RESULT" '{result: $r}')"
+done
+```
+
+**SSE watch (Phase 2 / Slice 2A — for low-latency, real-time tracker-driven work):**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+export MARTHA_TOKEN="${MARTHA_TOKEN:?need token}"
+
+# `watch` writes one JSON line per assignment to stdout; reconnects automatically
+# with Last-Event-ID so no work is missed across transient network drops.
+martha tasks watch --team code-review --json | while IFS= read -r LINE; do
+  TYPE=$(echo "$LINE" | jq -r '.type // empty')
+  [ "$TYPE" = "task.assigned" ] || continue
+  TASK_ID=$(echo "$LINE" | jq -r '.data.id')
+
+  if ! martha tasks claim "$TASK_ID" --json >/dev/null 2>&1; then
+    # Lost the race to another team member — keep watching
+    continue
+  fi
+
+  ( while sleep 30; do martha tasks heartbeat "$TASK_ID" --json >/dev/null || break; done ) &
+  HB_PID=$!
+
+  RESULT=$(your-agent-here "$TASK_ID")
+
+  kill $HB_PID 2>/dev/null || true
+  martha tasks complete "$TASK_ID" --json --outcome "$(jq -n --arg r "$RESULT" '{result: $r}')"
+done
+```
+
+**When to choose which:**
+- **Polling**: simplest; tolerates seconds of latency; works without a team scope.
+- **Watch**: best for trackers (Linear/GitHub webhooks → instant assignment) and high-throughput teams. Requires `--team`. Server enforces team membership for agent service accounts.
+
+---
+
+## Teams
+
+Teams group agents and define how incoming work is distributed.
+
+```bash
+martha teams create --name "code-review" [--description "..."] [--routing round_robin|manual|external]
+martha teams list
+martha teams view <name-or-id>                # Members, current task counts, routing config
+martha teams update <name-or-id> [--name "..."] [--routing manual]
+martha teams delete <name-or-id> [--yes]
+martha teams add-member <team> <agent-name> [--role member|lead]
+martha teams remove-member <team> <agent-id>
+```
+
+**Routing strategies:**
+
+| Strategy | Behavior | Best for |
+|---|---|---|
+| `manual` | Admin sets `assigned_agent_id` explicitly | Heterogeneous teams, deliberate routing |
+| `round_robin` | Auto-assigns to next active member at task creation | Homogeneous worker pools (5x ork instances) |
+| `external` | Tasks land in queue; external orchestrator (e.g. Linear, GitHub Actions) decides who claims | Tracker-driven workflows |
+
+**Setting up an external agent on a team:**
+
+```bash
+# 1. Create the agent definition
+martha agents create --name ork-worker-1 --type external --description "ork instance #1" \
+  --tags code-review,refactoring
+
+# 2. Provision auth — service account is recommended for long-running agents
+martha agents provision-auth ork-worker-1 --method service-account
+# Copy client_id + client_secret immediately
+
+# 3. Create the team if it doesn't exist
+martha teams create --name code-review --routing round_robin
+
+# 4. Add the agent to the team
+martha teams add-member code-review ork-worker-1
+
+# 5. On the agent host
+export MARTHA_CLIENT_ID="<client_id>"
+export MARTHA_CLIENT_SECRET="<client_secret>"
+martha auth login --service-account
+martha tasks poll --json
+```
+
+---
+
+## Connections + Vault credentials
+
+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
+
+# List available tracker adapters + their config_schema
+curl -s -H "Authorization: Bearer $(martha auth token)" \
+  "$MARTHA_API_URL/api/admin/trackers" | jq
+
+# 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"
+
+# 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
+
+# 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>"
+```
+
+**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}`):
+   - `sync-task-status-{type}` — fires on `task.*` events with `external_ref` set
+   - `sync-task-activity-{type}` — fires on `task.activity.created`
+   - `inbound-tracker-{type}` — fires on `webhook.received` with matching `webhook_name`
+
+After creating the connection, paste the `webhook_url` + `webhook_secret` into your tracker's webhook configuration page (Linear/GitHub/GitLab settings).
+
+---
+
+## Triggers + Events + Webhooks
+
+Triggers wire events to workflow or platform-function dispatches.
+
+```bash
+# Triggers
+martha triggers list [--active] [--limit 50]
+martha triggers create -f trigger.yaml
+martha triggers get <name>
+martha triggers update <name> -f trigger.yaml
+martha triggers delete <name> [--yes]
+martha triggers test <name> --event '{"type": "task.completed", "data": {...}}'   # Dry-run
+
+# Events (browse what's flowing)
+martha events list [--type task.*] [--since 1h] [--limit 50]
+martha events types                      # Available event types with sample payloads
+martha events emit --type custom.event --data '{"foo": "bar"}'   # Manual emit (admin only)
+
+# Webhooks
+martha webhooks list
+martha webhooks create --name <n> [--description "..."]   # Returns one-time secret
+martha webhooks rotate-secret <name>                       # New secret, invalidates old
+martha webhooks delete <name> [--yes]
+```
+
+**Trigger YAML:**
+
+```yaml
+name: notify-on-task-completion
+event_type: task.completed
+event_filter:
+  data:
+    priority: ["urgent", "high"]
+target_type: workflow              # or 'platform_function'
+target_name: send-completion-email
+input_mapping:
+  task_id: "{{event.data.task_id}}"
+  recipient: "carlos@nomadriver.co"
+is_active: true
+max_concurrent: 5                  # Concurrent dispatches per tenant
+dedup_key: "{{event.data.task_id}}"
+dedup_window_seconds: 300
+```
+
+**Filter operators:** Each filter value is a list. Within a list, ANY match counts. Across keys, ALL must match. Operators: literal equality, `[{"exists": true}]`, `[{"prefix": "foo"}]`, `[{"in": [...]}]`, `[{"regex": "..."}]`.
+
+---
+
+## Documents (RAG)
+
+Document collections are tenant-scoped containers that ingest files (PDF, DOCX, MD, etc.) and serve them for retrieval.
+
+```bash
+# Collections
+martha documents collections [--inactive] [--limit 50]
+martha documents collection <id>               # Stats, ingestion status, total size
+martha documents create-collection --name "My Docs" [--description "..."]
+
+# Document lifecycle
+martha documents upload <collection-id> <file> [--wait] [--follow]   # --follow streams ingestion progress
+martha documents list <collection-id> [--inactive] [--limit 50]
+martha documents get <doc-id>                  # Full metadata + chunk count
+martha documents status <doc-id> [--follow]    # Ingestion progress: validate → parse → embed → finalize
+martha documents download <doc-id> [--expires 3600]   # Presigned URL (default 1h)
+martha documents delete <doc-id> [--yes]
+martha documents reingest <doc-id> [--wait] [--follow]   # Re-run ingestion (after pipeline upgrade)
+martha documents page-images <doc-id> [--expires 3600]   # Presigned URLs for VLM-described pages
+
+# Search & query
+martha documents search <collection-id> "search query" [--max-results 10]   # Hybrid keyword+vector
+martha documents query <collection-id> "question" [--max-chunks 10] [--model claude-sonnet-4-5]   # RAG with answer
+```
+
+**Ingestion stages (visible in `status --follow`):**
+1. `validate` — MIME type, size limits, content scan
+2. `parse_and_chunk` — Docling extraction + HybridChunker + page classification
+3. `enrich` — embed + VLM describe (visual pages) + ColPali index (parallel, all non-fatal)
+4. `finalize` — write to `document_chunks`, mark ready
+
+A failed enrich step does NOT fail the document — it falls back to keyword-only search.
+
+---
+
+## 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.
+
+```bash
+martha approvals list [--status pending|approved|rejected|expired] [--assigned-to USER] [--limit 50]
+martha approvals stats
+martha approvals get <id>                                 # Context summary, workflow context
+martha approvals approve <id> [--comment "looks good"]
+martha approvals reject <id> [--comment "needs more data"]
+```
+
+The workflow execution resumes within seconds of approval/rejection (Temporal signal).
+
+---
+
+## Citations (RAG provenance)
+
+Citations link an LLM response to specific document chunks it consulted. They survive their source documents (no FK).
+
+```bash
+# Browse citations for an execution / message / approval
+martha citations list --execution <id>
+martha citations list --message <id>
+martha citations get <citation-id>                        # Quoted text, page range, verification status
+martha citations stats                                    # Total / verified / failed / pending
+martha citations verify <citation-id>                     # Re-runs exact/normalized/fuzzy matching
+```
+
+Available verification states: `verified`, `failed`, `pending`, `unverified`, `out_of_provenance`.
+
+---
+
+## Clients (chat API consumers)
+
+Clients are the consumer-side identity for the chat API (web frontend, SMS sender, voice line). Each Client has allowlists for which functions, workflows, and agents the client's sessions can use.
+
+```bash
+martha clients list [--limit 50]
+martha clients get <name-or-id>
+martha clients create --name <n> [--system-prompts '{"default": "..."}'] [--keycloak-client-id <id>]
+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 access <name-or-id>                                    # All grants for this client
+```
+
+---
+
+## Sessions + Chat
+
+```bash
+martha sessions list [--search QUERY] [--limit 20] [--type api|sms|whatsapp]
+martha sessions get <session-id>                          # Messages + tool calls
+martha sessions delete <session-id> [--yes]
+
+# Interactive chat (REPL)
+martha chat [--session <id>] [--client <name>] [--message "text"] [--show-tools]
+
+# Single-message mode
+martha chat --client web --message "What's the weather?"  # Creates new session, prints response
+```
+
+`--show-tools` prints each tool call + result inline so you can debug agent reasoning.
+
+---
+
+## Integrations (OpenAPI specs + plugins)
+
+Integrations are external API surfaces. Three types: `core` (`@platform_function`), `plugin` (Martha-published), `connected` (OpenAPI spec import), `custom` (manual function definitions).
+
+```bash
+martha integrations list                                  # All four sections
+martha integrations specs [--inactive]                    # OpenAPI specs only
+martha integrations sync <spec-id> [--force]              # Re-pull and reconcile (--force skips hash check)
+martha integrations import-openapi --source <url> --name <name> \
+    [--prefix <p>] [--auth-scheme bearer] [--auth-value '${API_KEY}'] \
+    [--include-tags tag1,tag2] [--exclude-tags admin] [--dry-run]
+martha integrations plugins                               # Installed plugins
+martha integrations plugin <name>                         # Plugin manifest + resources
+
+# Plugin proxy — call plugin endpoints directly (debugging)
+martha integrations proxy <plugin> GET|POST|PUT|DELETE <path> [--data '{}'] [--query 'k=v']
+```
+
+**OpenAPI import flow:**
+1. `--dry-run` first to see what functions would be created
+2. Resolve any naming conflicts (use `--prefix`)
+3. Re-run without `--dry-run` to apply
+4. Use `martha agents add-function` to grant new functions to agents
+5. Use `martha integrations sync <spec-id>` to refresh after the upstream API changes
+
+### Function authentication patterns
+
+Functions imported from OpenAPI inherit auth from the spec's `securitySchemes`. To bridge to Vault credentials, set `credential_source` on the function's `auth` block:
+
+```yaml
+kind: Function
+name: example-create-order
+definition:
+  endpoint: https://example.com/orders
+  http_method: POST
+  auth:
+    scheme: bearer
+    header: Authorization
+    credential_source: example_prod        # Vault key for the credential
+    # value: null — left null; resolved at runtime from Vault
+```
+
+`FunctionHandler._resolve_credentials()` walks 4 tiers in priority order:
+1. **Session** — `vault.get_credential("sessions", session_id, credential_source)`
+2. **Client** — `vault.get_credential("clients", str(client_id), credential_source)`
+3. **Tenant by credential_source** — direct Vault lookup
+4. **Tenant by Connection** — looks up `Connection.credential_source` for `integration_name`, then Vault
+
+If all 4 miss, falls back to baked-in `auth.value` (legacy). Use `martha agents provision-auth` for agent-scoped credentials, or the connections API for integration-scoped ones.
+
+---
+
+## Operational commands
+
+```bash
+martha status                            # Connection + auth + Vault + Temporal health summary
+martha models [--provider anthropic|openai|google]   # Available LLM models with cost
+martha messaging health                  # Infobip/Twilio status
+martha messaging send-sms --to <number> --from <sender> --content "text"
+martha config show                       # Resolved config (token-redacted)
+martha config set <key> <value>          # Update profile config
+martha config profiles                   # List + active marker
+martha config use <profile>              # Switch active profile
+```
+
+---
+
+## Patterns (cookbook)
+
+### Create + grant + execute a workflow end-to-end
+
+```bash
+# 1. Define functions + workflow declaratively
+cat > pipeline.yaml <<'EOF'
+kind: Function
+name: fetch-orders
+definition:
+  endpoint: https://api.example.com/orders
+  http_method: GET
+  auth:
+    scheme: bearer
+    credential_source: example_prod
+---
+kind: Workflow
+name: daily-orders-summary
+definition:
+  nodes:
+    - id: fetch
+      type: function
+      config: { function_name: fetch-orders }
+    - id: summarize
+      type: llm
+      config:
+        prompt: "Summarize: {{steps.fetch.output}}"
+        model: claude-sonnet-4-5
+  edges: [{source: fetch, target: summarize}]
+EOF
+
+martha definitions apply -f pipeline.yaml --yes
+
+# 2. Set up the credential (one-time per tenant)
+# Use the admin UI at /settings, or POST to /api/admin/connections
+
+# 3. Execute
+martha workflows execute daily-orders-summary --inputs '{}' --wait --follow
+```
+
+### External agent on a team — full setup
+
+```bash
+# Admin side
+martha agents create --name ork-1 --type external --tags refactoring
+martha agents provision-auth ork-1 --method service-account --json
+# Copy client_id + client_secret from output
+
+martha teams create --name refactoring-team --routing round_robin
+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
+martha auth login --service-account
+martha tasks poll --json   # Should return open team-scoped tasks
+```
+
+### Tracker integration — Linear
+
+```bash
+# 1. Create a Linear connection via admin UI: /settings > Trackers > Linear > Connect
+#    Provide: API Key (lin_api_...), Team ID (UUID from team URL)
+#    On success, copy the webhook_url + webhook_secret
+
+# 2. Configure Linear webhook
+#    Linear settings > API > Webhooks > New webhook
+#    URL: <webhook_url>, Secret: <webhook_secret>
+#    Subscribe to: Issues, Comments
+
+# 3. Verify the auto-created triggers
+martha triggers list --active | grep linear
+# Expect: sync-task-status-linear, sync-task-activity-linear, inbound-tracker-linear
+
+# 4. Test by creating a Linear issue — Martha should create a corresponding task
+martha tasks list --json | jq '.[] | select(.tracker_type == "linear")'
+```
+
+### Reingest documents after VLM upgrade
+
+```bash
+COLL=<collection-id>
+martha documents list $COLL --json | jq -r '.[] | .id' | while read DOC; do
+  martha documents reingest $DOC --wait
+done
+```
+
+### Debug a failed task
+
+```bash
+TASK=<id>
+martha tasks view $TASK --json | jq '{status, error_message, retry_count, last_checkpoint, executor_id}'
+
+# Look at the workflow execution if any
+EXEC=$(martha tasks view $TASK --json | jq -r '.workflow_execution_id')
+[ -n "$EXEC" ] && martha workflows execution $EXEC
+
+# Check audit log for the executor
+SVC=$(martha tasks view $TASK --json | jq -r '.executor_id')
+martha events list --since 24h --json | jq ".[] | select(.data.executor_id == \"$SVC\")"
+```
+
+### Bulk grant many functions to an agent
+
+```bash
+AGENT=my-agent
+martha integrations specs --json | jq -r '.[] | select(.name == "linear") | .id' | while read SPEC; do
+  martha functions list --source openapi --json | jq -r ".[] | select(.spec_id == \"$SPEC\") | .name" | while read FN; do
+    martha agents add-function $AGENT $FN
+  done
+done
+```
+
+---
+
+## Troubleshooting
+
+### "auth failure" (exit 2)
+- `martha auth status` — check the token isn't expired or for a different tenant
+- For service accounts: confirm `MARTHA_CLIENT_SECRET` matches the value from the most recent `provision-auth`
+- For human users: re-login (`martha auth login --username ... --password ...`)
+
+### "not found" (exit 3) when the entity exists in the UI
+- Tenant mismatch — your token belongs to a different tenant than where the entity lives
+- Run `martha auth status` to see your `tenant_id`, then check the entity's tenant in the admin UI
+
+### Workflow execution stuck in "running"
+- `martha workflows execution <id> --follow` — see which node is blocking
+- `martha approvals list --status pending` — common cause is a waiting `approval_gate`
+- For agent_loop nodes: check the agent's tool grants and credential resolution chain
+
+### Function returns 401 from upstream API
+- Check the function's `auth.credential_source` matches a Vault entry: `martha auth token` then `curl /api/admin/connections | jq` to find the connection
+- Verify the connection's `status` is `active` (rotate if expired)
+- For OAuth2 connections: a 401 may trigger automatic token refresh; check `events list --type oauth.refresh.*`
+
+### Task heartbeat returns 409 unexpectedly
+- Lease expired — your agent didn't heartbeat in time. Default lease is 300s; reduce work granularity or increase lease.
+- Another agent claimed it after a stale event. Inspect: `martha tasks view <id> --json | jq '{executor_id, lease_expires_at, retry_count}'`
+
+### Tracker webhook not creating tasks
+- Check the inbound trigger is active: `martha triggers list | grep inbound-tracker`
+- Check recent webhook events: `martha events list --type webhook.received --since 1h`
+- Look for HMAC signature failures in API logs (per-webhook secret mismatch)
+- Verify the connection still has `status: active`
+
+### "DuplicateColumn" alembic error on deploy
+- Migration trying to add a column that already exists. Check if a previous migration in the chain added it via a different path (this happened with `s4t5u6v7w8x9` and `u6v7w8x9y0z1`). Make the duplicate migration idempotent with `IF NOT EXISTS`.
+
+---
+
+## Conventions
+
+- **Always pass `--json`** when scripting. Human output may include color codes and is not parse-stable.
+- **Always pass `--yes`** in non-TTY contexts. The CLI errors instead of silently cancelling — this prevents CI from completing without doing anything.
+- **Tenant comes from the token**, never from a flag. To switch tenants, switch profiles.
+- **Time fields are ISO 8601 with timezone** in JSON output. Local-format dates appear only in human output.
+- **Pagination:** all `list` commands accept `--limit` (default 50, max 200) and most accept `--offset`. There's no cursor pagination yet.
+- **Soft delete is default.** `delete` without `--hard` marks `is_active=false` and keeps history. `--hard` purges. Tombstoned entities don't appear in `list` unless you pass `--inactive`.