@pixelml/agenticflow-cli 1.5.0 → 1.5.2

package/dist/bin/agenticflow.js

@@ -2,6 +2,18 @@
 /**
  * AgenticFlow CLI entry point.
  */
+// SECURITY: Some parent environments (notably certain Claude Code launch
+// aliases) set NODE_TLS_REJECT_UNAUTHORIZED=0 for their own reasons. When the
+// CLI inherits that env, Node prints a noisy and alarming warning on EVERY
+// invocation AND the CLI's HTTPS calls to api.agenticflow.ai skip cert
+// verification. We talk to a public HTTPS endpoint with a valid cert — we
+// should never opt out of TLS verification. Unset the env var before anything
+// else imports it, unless the user explicitly opts in via AF_INSECURE_TLS=1
+// (e.g. for a local dev backend with a self-signed cert).
+if (process.env["NODE_TLS_REJECT_UNAUTHORIZED"] === "0" &&
+    process.env["AF_INSECURE_TLS"] !== "1") {
+    delete process.env["NODE_TLS_REJECT_UNAUTHORIZED"];
+}
 import { runCli } from "../cli/main.js";
 runCli().catch((err) => {
     const message = err instanceof Error ? err.message : String(err);

package/dist/bin/agenticflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"agenticflow.js","sourceRoot":"","sources":["../../src/bin/agenticflow.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACrB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO;SACR,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"agenticflow.js","sourceRoot":"","sources":["../../src/bin/agenticflow.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,yEAAyE;AACzE,8EAA8E;AAC9E,2EAA2E;AAC3E,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,4EAA4E;AAC5E,0DAA0D;AAC1D,IACE,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,KAAK,GAAG;IACnD,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG,EACtC,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAC;AACrD,CAAC;AAED,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACrB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;YACzB,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,WAAW;YACjB,OAAO;SACR,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACf,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/changelog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAiGrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,eAAO,MAAM,SAAS,EAAE,cAAc,EAsIrC,CAAC;AAEF,wBAAgB,kBAAkB,IAAI,cAAc,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE"}

package/dist/cli/changelog.js

@@ -5,6 +5,43 @@
  * and displayed after upgrade.
  */
 export const CHANGELOG = [
+    {
+        version: "1.5.2",
+        date: "2026-04-14",
+        highlights: [
+            "`af workforce run --trigger-data '{...}'` now auto-wraps in the server's required `{trigger_data: ...}` envelope. Previously you had to pass `{\"trigger_data\":{\"topic\":\"AI\"}}` which felt like a CLI bug. Explicit wrapping still works (pass-through)",
+            "`af workforce delete` returns the consistent `agenticflow.delete.v1` envelope instead of bare `null`. Scripts now get the same shape as `af agent delete`",
+            "`af mcp-clients list --name-contains <substr> --fields id,name` — same filter + projection flags as `af agent list`. Essential for workspaces with dozens of MCP clients",
+            "`af mcp-clients inspect` surfaces the underlying `fetch_error` + `classification_reason` when tools can't be enumerated. Stops returning a misleading `pattern: unknown` that callers might treat as 'safe to attach'",
+            "`af schema <resource> --field <name>` now resolves against top-level schema keys too (not just create.optional). Lets you drill into `schema`, `update`, `stream` subtrees — e.g. `af schema workforce --field schema --json` returns the node_shape + edge_shape + agent_node_input docs",
+            "`af schema agent` clarifies that `project_id` is REQUIRED on create (server does NOT auto-inject for agents, unlike workforces). Separates the contract per resource",
+        ],
+        for_ai: [
+            "When you hit a 422 `body.trigger_data missing` on `workforce run`, upgrade to 1.5.2 — the CLI now auto-wraps",
+            "If `mcp-clients inspect` returns `classification_reason: 'fetch_failed'` or `'unauthenticated'`, DO NOT attach that client to an agent — re-auth in the web UI first",
+            "Filter MCP clients with `af mcp-clients list --name-contains 'google docs' --fields id,name --json` — no more grep-piping",
+            "Drill into any schema subtree: `af schema workforce --field schema --json` returns graph shape; `af schema agent --field mcp_clients --json` returns attach shape",
+            "Consistent delete envelope: every `af <resource> delete` returns `{schema:'agenticflow.delete.v1', deleted:true, id, resource}` on success",
+        ],
+    },
+    {
+        version: "1.5.1",
+        date: "2026-04-14",
+        highlights: [
+            "CLI unsets inherited NODE_TLS_REJECT_UNAUTHORIZED=0 at startup — fixes the noisy TLS warning that leaked to every invocation AND restores certificate verification for the CLI's HTTPS calls. Opt back in with AF_INSECURE_TLS=1 if you're running a local dev backend with a self-signed cert",
+            "`af agent list --name-contains <substr>` — client-side case-insensitive name filter. Stop grep-piping in busy workspaces",
+            "`af schema <resource> --field <name>` — drill into a single field's documented shape (useful for nested fields like mcp_clients, response_format, task_management_config)",
+            "`af schema agent` now documents the 12 previously-undocumented optional fields (mcp_clients, code_execution_tool_config, response_format, knowledge, skills_config, etc.) with shape hints, plus the `update` block + null_rejected_fields list (matches what `af agent update --patch` auto-strips)",
+            "`af schema workforce` — new schema entry explaining workforce create + bulk PUT /schema shape. Covers node types, edge connection_type enum (next_step | condition | ai_condition), and the agent_id requirement on type='agent' nodes",
+            "`af bootstrap --json` commands cheat-sheet now surfaces delete_agent, delete_workforce, list_agents_filtered, and get_schema_field — closes the 'how do I clean up' discoverability gap",
+        ],
+        for_ai: [
+            "Expected journey for a fresh agent operator:  (1) af whoami  →  (2) af bootstrap --json  →  (3) af playbook first-touch (or migrate-from-paperclip if coming from Paperclip)  →  (4) af schema <resource> --field <name> for any unclear payload shape  →  (5) build with --dry-run, then live  →  (6) cleanup with af <resource> delete",
+            "Use `af agent list --name-contains <substr> --fields id,name --json` to find your own test agents in a populated workspace before bulk delete",
+            "`af schema agent --field mcp_clients --json` returns the documented attach-shape with run_behavior + per-tool allow map — no more guessing",
+            "If you hit TLS cert errors against a self-signed backend, set AF_INSECURE_TLS=1 (do NOT set NODE_TLS_REJECT_UNAUTHORIZED directly — CLI now unsets it at startup)",
+        ],
+    },
     {
         version: "1.5.0",
         date: "2026-04-14",

package/dist/cli/changelog.js.map

@@ -1 +1 @@
-{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,iKAAiK;YACjK,mIAAmI;YACnI,4JAA4J;YAC5J,qJAAqJ;YACrJ,8GAA8G;YAC9G,yGAAyG;SAC1G;QACD,MAAM,EAAE;YACN,mMAAmM;YACnM,wLAAwL;YACxL,wGAAwG;YACxG,gGAAgG;YAChG,iIAAiI;YACjI,oIAAoI;SACrI;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,2GAA2G;YAC3G,+MAA+M;YAC/M,2LAA2L;YAC3L,kJAAkJ;YAClJ,2GAA2G;YAC3G,2GAA2G;YAC3G,iKAAiK;YACjK,kHAAkH;YAClH,uHAAuH;SACxH;QACD,MAAM,EAAE;YACN,6LAA6L;YAC7L,uLAAuL;YACvL,4PAA4P;YAC5P,+JAA+J;YAC/J,2GAA2G;SAC5G;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,uEAAuE;YACvE,mFAAmF;YACnF,yFAAyF;YACzF,gFAAgF;YAChF,kEAAkE;YAClE,uFAAuF;YACvF,iEAAiE;YACjE,uEAAuE;YACvE,yDAAyD;YACzD,wDAAwD;YACxD,6EAA6E;YAC7E,6GAA6G;SAC9G;QACD,MAAM,EAAE;YACN,6FAA6F;YAC7F,+GAA+G;YAC/G,qFAAqF;YACrF,6EAA6E;YAC7E,qEAAqE;YACrE,oHAAoH;YACpH,wGAAwG;YACxG,mGAAmG;SACpG;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,gEAAgE;YAChE,uEAAuE;YACvE,mDAAmD;YACnD,4CAA4C;SAC7C;QACD,MAAM,EAAE;YACN,6CAA6C;YAC7C,6DAA6D;SAC9D;KACF;IACD;QACE,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE;YACV,kCAAkC;YAClC,6CAA6C;YAC7C,qCAAqC;SACtC;QACD,MAAM,EAAE;YACN,0CAA0C;SAC3C;KACF;CACF,CAAC;AAEF,MAAM,UAAU,kBAAkB;IAChC,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,GAAG,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;IAC9D,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"changelog.js","sourceRoot":"","sources":["../../src/cli/changelog.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CA2pKvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAy4BpC,wBAAgB,aAAa,IAAI,OAAO,CA81KvC;AAED,wBAAsB,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB3D"}

package/dist/cli/main.js

@@ -758,6 +758,7 @@ export function createProgram() {
     const SCHEMAS = {
         agent: {
             resource: "agent",
+            note: "`project_id` is REQUIRED in the body on agent create (server does NOT auto-inject from client config, unlike workforces). The CLI's local validator enforces this — grab the value from `af bootstrap --json > auth.project_id`. The `workspace_id` scoping is handled server-side via API key.",
             create: {
                 required: ["name", "tools", "project_id"],
                 optional: {
@@ -767,16 +768,63 @@ export function createProgram() {
                     system_prompt: "string",
                     recursion_limit: "number (10-500, default: 25)",
                     agent_type: "standard | autonomous (default: standard)",
+                    model_user_config: "object { temperature?, max_tokens?, max_input_tokens?, reasoning_effort? }",
+                    mcp_clients: "array of { mcp_client_id, run_behavior: 'auto_run' | 'confirm', description?, timeout?, tools?: {tool_name: {allowed: bool}} } — attach MCP tool providers",
+                    code_execution_tool_config: "object { enable: bool, enable_file_operations?: bool } — enable Python/JS code exec",
+                    file_system_tool_config: "object | null — enable file system tool",
+                    attachment_config: "object | null — file attachment config",
+                    response_format: "object | null — structured output schema for the agent's final response (JSON mode)",
+                    knowledge: "object | null — knowledge base / RAG configuration",
+                    skills_config: "object | null — skill pack configuration",
+                    task_management_config: "object | null — task queue / scheduling configuration",
+                    suggest_replies: "bool (default: true) — generate suggested follow-up replies",
+                    auto_generate_title: "bool (default: true) — auto-title new threads",
+                    welcome_message: "string — greeting on new thread",
+                    suggested_messages: "array of strings — pre-populated example prompts shown to users",
+                    sub_agents: "array — sub-agent configurations for agent teams",
+                    plugins: "array — plugin configurations",
                 },
                 example: { name: "My Agent", tools: [], project_id: "YOUR_PROJECT_ID" },
             },
+            update: {
+                note: "PUT /v1/agents/{id} — supply any subset of create fields. Prefer `af agent update --patch` to avoid round-tripping the full body.",
+                null_rejected_fields: [
+                    "suggest_replies_model", "suggest_replies_model_user_config", "suggest_replies_prompt_template",
+                    "knowledge", "task_management_config", "recursion_limit",
+                    "file_system_tool_config", "attachment_config", "response_format", "skills_config",
+                ],
+                null_rejected_note: "These fields must be OMITTED (not sent as null) on update — server rejects null. The CLI auto-strips when you use `af agent update` (with or without --patch).",
+            },
             stream: {
                 required: ["messages"],
                 optional: { id: "string (thread UUID for conversation continuity)" },
                 messages_item: { required: ["content"], optional: { role: "user (default)" } },
                 example: { messages: [{ content: "Hello", role: "user" }] },
             },
-            fields: ["id", "name", "description", "model", "visibility", "system_prompt", "tools", "mcp_clients", "plugins", "sub_agents", "agent_type", "recursion_limit", "created_at", "updated_at"],
+            fields: ["id", "name", "description", "model", "visibility", "system_prompt", "tools", "mcp_clients", "plugins", "sub_agents", "agent_type", "recursion_limit", "model_user_config", "code_execution_tool_config", "file_system_tool_config", "attachment_config", "response_format", "knowledge", "skills_config", "task_management_config", "suggest_replies", "auto_generate_title", "welcome_message", "suggested_messages", "created_at", "updated_at"],
+        },
+        workforce: {
+            resource: "workforce",
+            note: "AgenticFlow-native multi-agent DAG (nodes + edges). Create metadata first, then PUT /schema with the full graph.",
+            create: {
+                required: ["name"],
+                optional: {
+                    description: "string",
+                    recursion_limit: "number (default: 25)",
+                    error_handling_policy: "object { on_error: 'stop' | 'continue' | 'route', ... }",
+                    is_public: "bool (default: false)",
+                },
+                example: { name: "My Team Workforce", description: "What this team does" },
+                server_injects: "workspace_id and project_id are auto-injected from client config if absent",
+            },
+            schema: {
+                note: "PUT /v1/workspaces/{ws}/workforce/{id}/schema — atomic bulk graph replace. Server diffs current vs desired and applies create/update/delete.",
+                required: ["nodes", "edges"],
+                node_shape: { name: "string", type: "trigger | agent | output | router | condition | loop | tool | plugin | agent_team | agent_team_member | state_modifier", position: "{ x, y }", input: "object (per node_type)", meta: "object (optional)" },
+                edge_shape: { source_node_name: "string", target_node_name: "string", connection_type: "next_step | condition | ai_condition" },
+                agent_node_input: "type='agent' nodes REQUIRE a real agent_id in input. Create agents first, then reference.",
+            },
+            fields: ["id", "workspace_id", "project_id", "name", "description", "error_handling_policy", "is_public", "public_key", "current_version_id", "recursion_limit", "created_at", "updated_at"],
         },
         workflow: {
             resource: "workflow",
@@ -888,14 +936,18 @@ export function createProgram() {
                 run_agent: "af agent run --agent-id <id> --message <msg> --json",
                 create_agent: "af agent create --body <json> --dry-run --json",
                 list_agents: "af agent list --fields id,name,model --json",
+                list_agents_filtered: "af agent list --name-contains <substr> --fields id,name --json",
                 update_agent_patch: "af agent update --agent-id <id> --patch --body '{\"field\":\"value\"}' --json",
+                delete_agent: "af agent delete --agent-id <id> --json",
                 init_workforce: "af workforce init --blueprint <id> --json",
                 run_workforce: "af workforce run --workforce-id <id> --trigger-data '{}'",
                 publish_workforce: "af workforce publish --workforce-id <id> --json",
+                delete_workforce: "af workforce delete --workforce-id <id> --json",
                 inspect_mcp_client: "af mcp-clients inspect --id <id> --json",
                 deploy_to_paperclip: "af paperclip init --blueprint <id> --json   # DEPRECATED, use `af workforce init`",
                 send_webhook: "curl -X POST http://localhost:4100/webhook/webhook -H 'Content-Type: application/json' -d '{\"agent_id\":\"<id>\",\"message\":\"<msg>\"}'",
                 get_schema: "af schema <resource> --json",
+                get_schema_field: "af schema <resource> --field <field_name> --json",
                 get_playbook: "af playbook <topic>",
                 get_changelog: "af changelog --json",
             },
@@ -1019,14 +1071,15 @@ export function createProgram() {
     program
         .command("schema [resource]")
         .description("Show resource schema for payload construction. AI agents: use this to discover fields before building payloads.")
-        .action((resource) => {
+        .option("--field <name>", "Drill into a single field — returns its documented shape from create.optional (or create.required). Useful for nested fields like `mcp_clients`, `response_format`, `task_management_config`.")
+        .action((resource, opts) => {
         if (!resource) {
             if (isJsonFlagEnabled()) {
                 printResult({
                     schema: "agenticflow.schema.index.v1",
                     available: Object.keys(SCHEMAS),
                     usage: "af schema <resource> --json",
-                    hint: "Use 'af schema agent' to see agent create/stream payload schemas.",
+                    hint: "Use 'af schema agent' to see agent create/stream payload schemas. Use 'af schema agent --field mcp_clients' to drill into a single field.",
                 });
             }
             else {
@@ -1042,6 +1095,64 @@ export function createProgram() {
         if (!schema) {
             fail("schema_not_found", `Unknown resource: ${resource}`, `Available: ${Object.keys(SCHEMAS).join(", ")}`);
         }
+        // Field drilldown: resolve `--field X` against multiple schema locations.
+        // We look in this order: top-level sibling key (e.g. `schema`, `update`,
+        // `stream`), then create.required, then create.optional. This lets the
+        // drilldown return rich subtree docs (like `schema` node/edge shapes on
+        // the workforce resource) rather than "not found".
+        if (opts?.field) {
+            const fieldName = opts.field;
+            const s = schema;
+            let doc = null;
+            let location = null;
+            let isRequired = false;
+            if (fieldName in s && fieldName !== "resource" && fieldName !== "fields") {
+                doc = s[fieldName];
+                location = "top_level";
+            }
+            else {
+                const create = s.create ?? {};
+                const required = create.required ?? [];
+                const optional = create.optional ?? {};
+                if (required.includes(fieldName)) {
+                    doc = "required";
+                    isRequired = true;
+                    location = "create.required";
+                }
+                else if (fieldName in optional) {
+                    doc = optional[fieldName] ?? null;
+                    location = "create.optional";
+                }
+            }
+            const found = doc !== null && doc !== undefined;
+            const result = {
+                schema: "agenticflow.schema.field.v1",
+                resource: s.resource,
+                field: fieldName,
+                required: isRequired,
+                location,
+                doc,
+                found,
+                hint: !found
+                    ? `Field '${fieldName}' has no documented shape in the static schema. Candidates: top-level keys (${Object.keys(s).filter((k) => !["resource", "fields"].includes(k)).join(", ")}); create.required; create.optional. For live introspection, fetch an existing instance via 'af ${s.resource} get --${s.resource}-id <id> --json' and inspect the returned value for that field.`
+                    : undefined,
+            };
+            if (isJsonFlagEnabled()) {
+                printResult(result);
+            }
+            else {
+                console.log(`${s.resource}.${fieldName}${isRequired ? " (required)" : ""}${location ? ` [${location}]` : ""}`);
+                if (typeof doc === "string") {
+                    console.log(`  ${doc}`);
+                }
+                else if (doc !== null && doc !== undefined) {
+                    console.log(JSON.stringify(doc, null, 2).split("\n").map((l) => "  " + l).join("\n"));
+                }
+                if (result.hint)
+                    console.log(`  ${result.hint}`);
+            }
+            return;
+        }
         if (isJsonFlagEnabled()) {
             printResult(schema);
         }
@@ -3328,7 +3439,8 @@ export function createProgram() {
         .command("list")
         .description("List agents.")
         .option("--project-id <id>", "Project ID")
-        .option("--search <query>", "Search query")
+        .option("--search <query>", "Backend search query (server-side)")
+        .option("--name-contains <substr>", "Client-side case-insensitive substring filter on agent `name`. Use for quick filtering in busy workspaces.")
         .option("--limit <n>", "Limit results")
         .option("--offset <n>", "Offset")
         .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,model)")
@@ -3340,7 +3452,16 @@ export function createProgram() {
             limit: parseOptionalInteger(opts.limit, "--limit", 1),
             offset: parseOptionalInteger(opts.offset, "--offset", 0),
         });
-        printResult(applyFieldsFilter(data, opts.fields));
+        let filtered = data;
+        const nameContains = opts.nameContains;
+        if (nameContains && Array.isArray(data)) {
+            const needle = nameContains.toLowerCase();
+            filtered = data.filter((row) => {
+                const n = row["name"];
+                return typeof n === "string" && n.toLowerCase().includes(needle);
+            });
+        }
+        printResult(applyFieldsFilter(filtered, opts.fields));
     });
     agentCmd
         .command("get")
@@ -3940,28 +4061,54 @@ export function createProgram() {
         .option("--project-id <id>", "Project ID")
         .option("--limit <n>", "Limit")
         .option("--offset <n>", "Offset")
+        .option("--name-contains <substr>", "Client-side case-insensitive substring filter on client `name`. Essential in busy workspaces with dozens of MCP clients.")
+        .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,is_authenticated). Applies after --name-contains filter.")
         .option("--verify-auth", "Reconcile is_authenticated by calling `get` for each client — slower " +
         "but catches the case where list() reports auth=true but get() reveals " +
         "the underlying provider session is expired. N+1 call; use sparingly.")
         .action(async (opts) => {
         const client = buildClient(program.opts());
+        // Helper: apply client-side name filter + fields projection to a list response
+        const postFilter = (rows) => {
+            let out = rows;
+            const nameContains = opts.nameContains;
+            if (nameContains && Array.isArray(out)) {
+                const needle = nameContains.toLowerCase();
+                out = out.filter((r) => {
+                    const n = r["name"];
+                    return typeof n === "string" && n.toLowerCase().includes(needle);
+                });
+            }
+            return applyFieldsFilter(out, opts.fields);
+        };
         if (!opts.verifyAuth) {
-            await run(() => client.mcpClients.list({
-                workspaceId: opts.workspaceId,
-                projectId: opts.projectId,
-                limit: parseOptionalInteger(opts.limit, "--limit", 1),
-                offset: parseOptionalInteger(opts.offset, "--offset", 0),
-            }));
+            await run(async () => {
+                const rows = await client.mcpClients.list({
+                    workspaceId: opts.workspaceId,
+                    projectId: opts.projectId,
+                    limit: parseOptionalInteger(opts.limit, "--limit", 1),
+                    offset: parseOptionalInteger(opts.offset, "--offset", 0),
+                });
+                return postFilter(rows);
+            });
             return;
         }
-        // --verify-auth: list, then re-check each row's auth via get()
+        // --verify-auth: list, filter, then re-check each remaining row's auth via get()
         await run(async () => {
-            const rows = (await client.mcpClients.list({
+            let rows = (await client.mcpClients.list({
                 workspaceId: opts.workspaceId,
                 projectId: opts.projectId,
                 limit: parseOptionalInteger(opts.limit, "--limit", 1),
                 offset: parseOptionalInteger(opts.offset, "--offset", 0),
             }));
+            const nameContains = opts.nameContains;
+            if (nameContains) {
+                const needle = nameContains.toLowerCase();
+                rows = rows.filter((r) => {
+                    const n = r["name"];
+                    return typeof n === "string" && n.toLowerCase().includes(needle);
+                });
+            }
             const verified = await Promise.all(rows.map(async (row) => {
                 const id = row["id"];
                 if (!id)
@@ -3979,7 +4126,7 @@ export function createProgram() {
                     return { ...row, verified_auth_error: err instanceof Error ? err.message : String(err) };
                 }
             }));
-            return verified;
+            return applyFieldsFilter(verified, opts.fields);
         });
     });
     mcpClientsCmd
@@ -4018,16 +4165,38 @@ export function createProgram() {
                     ? (toolsBox.tools)
                     : [];
             const report = inspectMcpToolsPattern(tools);
+            // Surface the underlying fetch/auth error when the tools list couldn't
+            // be enumerated — previously we silently returned pattern="unknown",
+            // which callers mistook for "safe to attach." Now the `fetch_error`
+            // + `classification_reason` make the failure explicit.
+            const fetchError = raw["error"];
+            const isAuth = raw["is_authenticated"];
+            const classification_reason = tools.length > 0
+                ? "tools_enumerated"
+                : fetchError
+                    ? "fetch_failed"
+                    : isAuth === false
+                        ? "unauthenticated"
+                        : "unknown";
+            const additional_quirks = [...report.quirks];
+            if (tools.length === 0 && (fetchError || isAuth === false)) {
+                additional_quirks.unshift(`Cannot classify this MCP client's tools — ${classification_reason}. ` +
+                    (fetchError ? `Server reported: ${fetchError}. ` : "") +
+                    `Do NOT attach this client to an agent until the underlying issue is resolved. ` +
+                    `Re-auth via the AgenticFlow web UI (workspaces/<ws>/mcp/${clientId}).`);
+            }
             return {
                 schema: "agenticflow.mcp_client.inspect.v1",
                 client_id: clientId,
                 client_name: raw["name"] ?? null,
-                is_authenticated: raw["is_authenticated"] ?? null,
+                is_authenticated: isAuth ?? null,
                 tool_count: tools.length,
                 pattern: report.pattern, // "pipedream" | "composio" | "mixed" | "unknown"
+                classification_reason,
+                fetch_error: fetchError ?? null,
                 write_capable_tools: report.writeCapable,
                 pipedream_instruction_only_tools: report.pipedreamTools,
-                known_quirks: report.quirks,
+                known_quirks: additional_quirks,
                 playbook: "af playbook mcp-client-quirks",
             };
         });
@@ -4116,7 +4285,21 @@ export function createProgram() {
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .action(async (opts) => {
         const client = buildClient(program.opts());
-        await run(() => client.workforces.delete(opts.workforceId, { workspaceId: opts.workspaceId }));
+        try {
+            await client.workforces.delete(opts.workforceId, { workspaceId: opts.workspaceId });
+            // Server returns 204/null on success — wrap in the same delete envelope
+            // that `af agent delete` uses so scripts get a consistent shape.
+            printResult({
+                schema: "agenticflow.delete.v1",
+                deleted: true,
+                id: opts.workforceId,
+                resource: "workforce",
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            fail("request_failed", message);
+        }
     });
     workforceCmd
         .command("schema")
@@ -4175,13 +4358,24 @@ export function createProgram() {
         .description("Execute a workforce. Streams SSE events — each event prints as one JSON line. " +
         "Exits when the stream closes.")
         .requiredOption("--workforce-id <id>", "Workforce ID")
-        .option("--trigger-data <json>", "Trigger data (inline JSON or @file)", "{}")
+        .option("--trigger-data <json>", "Trigger input as inline JSON or @file. Pass the data your trigger node expects " +
+        "(e.g. `{\"topic\":\"AI\"}`) — the CLI automatically wraps it in the server's " +
+        "required `{trigger_data: ...}` envelope. If you pass `{\"trigger_data\":{...}}` " +
+        "explicitly, it's left as-is.", "{}")
         .option("--workspace-id <id>", "Workspace ID (overrides env)")
         .action(async (opts) => {
         const client = buildClient(program.opts());
-        const triggerData = loadJsonPayload(opts.triggerData);
+        const raw = loadJsonPayload(opts.triggerData);
+        // Server accepts `{trigger_data: {...}}`. If the caller already wrapped
+        // it (explicitly nested under trigger_data), pass through. Otherwise,
+        // wrap the user's payload. This is the ergonomics fix for friction S6 —
+        // previously passing `{topic:"..."}` returned `422: body.trigger_data
+        // missing` which looked like a CLI bug, not a payload shape bug.
+        const triggerBody = "trigger_data" in raw && typeof raw["trigger_data"] === "object" && raw["trigger_data"] !== null
+            ? raw
+            : { trigger_data: raw };
         try {
-            const response = await client.workforces.run(opts.workforceId, triggerData, {
+            const response = await client.workforces.run(opts.workforceId, triggerBody, {
                 workspaceId: opts.workspaceId,
             });
             if (!response.ok) {