fix(v1.6.4): codex round-1 + doc-bug — bootstrap degraded mode + workforce list filter

First codex (GPT-5) operator session in tmux produced 4 concrete
friction points. Addresses 3; F2 (local node-type schema) is bigger
scope, deferred. Also caught a real doc/code mismatch I shipped earlier.

Fixes:

1. (F1, codex) `af bootstrap` hid backend failure
   Previously returned `auth.health: false` alongside an empty `agents`
   and `workforces` array — indistinguishable from a genuinely empty
   workspace. Codex's exact words: "either a hard stop up front or a
   much louder degraded-mode signal."
   Now returns:
   - `auth.health_error` with the underlying fetch error message
   - `data_fresh: boolean` at top level
   - `data_fresh_hint` string when the backend is unreachable
   Plus a new `--strict` flag that exits non-zero on health failure,
   so CI pipelines don't race into mutations on a degraded workspace.

2. (F3, codex) `af workforce init --help` stale paperclip ref
   Help text said `--blueprint <slug>  Blueprint id (run 'af paperclip
   blueprints' to list)`. Replaced with inline blueprint slugs + a
   pointer to `af bootstrap --json > blueprints[]`.

3. (Own bug caught during doc pass) `af workforce list` missing
   `--name-contains` + `--fields` flags. Documented in v1.6.1 changelog
   and in both README and command-reference gitbook pages, but the code
   never shipped the flags — every invocation returned 'unknown option'.
   Now implemented as client-side filter + projection, matching the
   `agent list` / `mcp-clients list` pattern.

Deferred (F2): bundling workforce node-type schemas locally so
`af workforce node-types` works offline. Non-trivial — requires
versioning the node-type catalog and syncing with the backend.

Tests: 392 pass, 14 skip, 10 todo. Zero regressions.

Notes:
- Codex validated all prior v1.6 improvements: bootstrap/schema/--dry-run
  called "genuinely useful", "strong", "excellent". Consistent error
  envelope (agenticflow.error.v1) acknowledged. --skeleton-only deemed
  a "smart discovery path".
- Codex's sandbox blocked outbound HTTPS entirely, so the journey
  was local-shape + dry-run. The network-failure signal itself is what
  drove the bootstrap degraded-mode fix.

Author: seanphan

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelml/agenticflow-cli",
-  "version": "1.6.3",
+  "version": "1.6.4",
   "description": "AgenticFlow CLI for agent-native API operations.",
   "license": "Apache-2.0",
   "repository": {

packages/cli/src/cli/changelog.ts

@@ -13,6 +13,22 @@ export interface ChangelogEntry {
 }
 
 export const CHANGELOG: ChangelogEntry[] = [
+  {
+    version: "1.6.4",
+    date: "2026-04-14",
+    highlights: [
+      "`af bootstrap` now surfaces a `data_fresh` boolean and `data_fresh_hint` when the backend health check fails — empty `agents`/`workforces` arrays no longer look identical to 'workspace is empty'. Also added `auth.health_error` with the underlying fetch error message",
+      "`af bootstrap --strict` exits non-zero when backend health is false — use in CI to prevent downstream mutations against a degraded workspace",
+      "`af workforce list --name-contains <substr> --fields id,name --json` — same client-side filter + projection as `af agent list` and `af mcp-clients list`. Closes a documentation lie where the flag was advertised but not implemented",
+      "`af workforce init --blueprint --help` no longer references the deprecated `af paperclip blueprints` as the canonical list source. Points at `af bootstrap --json > blueprints[]` with inline slug names",
+      "README + CONTEXT.md + the gitbook-hosted `docs/09-developers/cli/` pages updated to v1.6 surface (native workforce lead, `--patch`, MCP inspect, paperclip deprecation notice, error-envelope shape)",
+    ],
+    for_ai: [
+      "After `af bootstrap --json`, check `data_fresh`. If false, the empty lists are UNVERIFIED — don't assume the workspace is empty. Fix network/auth before mutating",
+      "In CI, run `af bootstrap --strict` instead of the bare form — non-zero exit guards the rest of the pipeline",
+      "`af workforce list --fields id,name --name-contains <substr> --json` now works (was documented but broken in prior versions) — use it to find your own test workforces before bulk delete",
+    ],
+  },
   {
     version: "1.6.3",
     date: "2026-04-14",

packages/cli/src/cli/main.ts

@@ -1139,22 +1139,27 @@ export function createProgram(): Command {
   program
     .command("bootstrap")
     .description("Single-command AI agent setup: verify auth, list agents, return schemas. Combines context + doctor + schema + agent list.")
-    .action(async () => {
+    .option("--strict", "Exit non-zero when the backend health check fails. Useful in CI / for scripts that shouldn't proceed into a degraded workspace.")
+    .action(async (opts) => {
       // Combine everything an AI needs in one response
       const client = buildClient(program.opts());
       const token = resolveToken(program.opts());
 
       let health = false;
+      let healthError: string | null = null;
       let agents: unknown[] = [];
       try {
         const sdk = client.sdk;
         const resp = await sdk.get("/v1/health");
         health = resp.ok;
-      } catch { /* unhealthy */ }
+        if (!resp.ok) healthError = `HTTP ${resp.statusCode}`;
+      } catch (err) {
+        healthError = err instanceof Error ? err.message : String(err);
+      }
 
       try {
         agents = (await client.agents.list({ limit: 10 })) as unknown[];
-      } catch { /* no agents or unauth */ }
+      } catch { /* no agents or unauth — list stays empty */ }
 
       // Workforces are the AgenticFlow-native multi-agent primitive. Fetch
       // the first 10 for the bootstrap snapshot. Tolerate failure (endpoint
@@ -1164,14 +1169,24 @@ export function createProgram(): Command {
         workforces = (await client.workforces.list({ limit: 10 })) as unknown[];
       } catch { /* no workforces or unauth */ }
 
+      // Annotate data-freshness so callers know whether the empty arrays mean
+      // "nothing there" or "couldn't verify because backend was unreachable".
+      // Matches codex-round-1 friction point F1 — previously an empty agents[]
+      // looked identical whether the workspace was empty or the API was down.
+      const dataFresh = health;
       printResult({
         schema: "agenticflow.bootstrap.v1",
         auth: {
           authenticated: !!token,
           health,
+          health_error: healthError,
           workspace_id: client.sdk.workspaceId,
           project_id: client.sdk.projectId,
         },
+        data_fresh: dataFresh,
+        data_fresh_hint: dataFresh
+          ? undefined
+          : "Backend unreachable — `agents`, `workforces`, and the `blueprints` array are the local/bundled shape only. Empty lists DO NOT mean 'nothing in your workspace'. Fix network/auth before mutating.",
         agents: Array.isArray(agents)
           ? agents.slice(0, 10).map((a) => {
             const ag = a as Record<string, unknown>;
@@ -1228,6 +1243,11 @@ export function createProgram(): Command {
           datasets: webUrl("datasets", { workspaceId: client.sdk.workspaceId }),
         },
       });
+      // --strict turns degraded-backend into a non-zero exit so CI / automation
+      // doesn't race ahead into mutations against an unreachable API.
+      if (opts.strict && !health) {
+        process.exit(1);
+      }
     });
 
   // ═════════════════════════════════════════════════════════════════
@@ -4833,13 +4853,26 @@ export function createProgram(): Command {
     .option("--workspace-id <id>", "Workspace ID (overrides env)")
     .option("--limit <n>", "Limit")
     .option("--offset <n>", "Offset")
+    .option("--name-contains <substr>", "Client-side case-insensitive substring filter on workforce `name`.")
+    .option("--fields <fields>", "Comma-separated fields to return (e.g. id,name,is_public). Applies after --name-contains.")
     .action(async (opts) => {
       const client = buildClient(program.opts());
-      await run(() => client.workforces.list({
-        workspaceId: opts.workspaceId,
-        limit: parseOptionalInteger(opts.limit as string | undefined, "--limit", 1),
-        offset: parseOptionalInteger(opts.offset as string | undefined, "--offset", 0),
-      }));
+      await run(async () => {
+        const rows = await client.workforces.list({
+          workspaceId: opts.workspaceId,
+          limit: parseOptionalInteger(opts.limit as string | undefined, "--limit", 1),
+          offset: parseOptionalInteger(opts.offset as string | undefined, "--offset", 0),
+        });
+        let out = rows;
+        const needle = (opts.nameContains as string | undefined)?.toLowerCase();
+        if (needle && Array.isArray(out)) {
+          out = (out as Array<Record<string, unknown>>).filter((r) => {
+            const n = r["name"];
+            return typeof n === "string" && n.toLowerCase().includes(needle);
+          });
+        }
+        return applyFieldsFilter(out, opts.fields as string | undefined);
+      });
     });
 
   workforceCmd
@@ -5228,7 +5261,7 @@ export function createProgram(): Command {
       "them into a runnable DAG. Use --skeleton-only for the old v1.5 behavior " +
       "(trigger + output + blueprint metadata, no agents).",
     )
-    .requiredOption("--blueprint <slug>", "Blueprint id (run `af paperclip blueprints` to list)")
+    .requiredOption("--blueprint <slug>", "Blueprint id. See `af bootstrap --json > blueprints[]` for available ids (dev-shop, marketing-agency, sales-team, content-studio, support-center, amazon-seller).")
     .option("--name <name>", "Workforce name (defaults to blueprint name)")
     .option("--workspace-id <id>", "Workspace ID (overrides env)")
     .option("--project-id <id>", "Project ID to use for agent creation (defaults to env / client config)")