@zibby/skills 0.1.33 → 0.1.35

package/dist/workflow-builder.d.ts

@@ -0,0 +1,245 @@
+export namespace workflowBuilderSkill {
+    export let id: string;
+    export let description: string;
+    export let envKeys: any[];
+    export { PROMPT_FRAGMENT as promptFragment };
+    export let tools: ({
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                nodes: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            name: {
+                                type: string;
+                                description: string;
+                            };
+                            description: {
+                                type: string;
+                                description: string;
+                            };
+                            inputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                            outputFields: {
+                                type: string;
+                                items: {
+                                    type: string;
+                                };
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                edges: {
+                    type: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            from: {
+                                type: string;
+                                description: string;
+                            };
+                            to: {
+                                type: string;
+                                description: string;
+                            };
+                            condition: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                    description: string;
+                };
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                spec: {
+                    type: string;
+                    description: string;
+                    properties: {
+                        name: {
+                            type: string;
+                        };
+                        description: {
+                            type: string;
+                        };
+                        nodes: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                        edges: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                        };
+                    };
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                workflowName: {
+                    type: string;
+                    description: string;
+                };
+                nodeName: {
+                    type: string;
+                    description: string;
+                };
+                description: {
+                    type: string;
+                    description: string;
+                };
+                inputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                outputFields: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                name?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                projectId: {
+                    type: string;
+                    description: string;
+                };
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                topic?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+                topic?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        input_schema: {
+            type: string;
+            properties: {
+                topic: {
+                    type: string;
+                    description: string;
+                };
+                name?: undefined;
+                description?: undefined;
+                nodes?: undefined;
+                edges?: undefined;
+                spec?: undefined;
+                workflowName?: undefined;
+                nodeName?: undefined;
+                inputFields?: undefined;
+                outputFields?: undefined;
+                projectId?: undefined;
+            };
+            required?: undefined;
+        };
+    })[];
+    export function handleToolCall(name: any, args: any, context: any): Promise<string>;
+    export function resolve(): any;
+}
+declare const PROMPT_FRAGMENT: "## Workflow Builder\n\nYou can help users build custom AI workflows using the Zibby workflow framework.\n\n### What makes Zibby workflows different\nEach node invokes a **real AI agent** (Cursor, Claude, Codex, or Gemini) \u2014 not a thin LLM API wrapper.\nThat means every node has full agent capabilities: tool use, MCP servers (browser, GitHub, Jira, Slack),\nmulti-turn reasoning, and structured output validation via Zod schemas.\n\nKey differentiators:\n- **Agent-powered nodes** \u2014 each step runs a full AI agent (cursor-agent, claude, codex, gemini CLI) with tool access and MCP skills, not a simple chat completion call.\n- **Structured output** \u2014 every node declares a Zod schema; the framework validates and parses the agent's response automatically.\n- **Conditional routing** \u2014 edges can branch on agent-produced fields (e.g., `state.triage.priority === 'critical'`), enabling intelligent decision graphs.\n- **MCP skill injection** \u2014 nodes declare `skills: [SKILLS.BROWSER, SKILLS.GITHUB]` and the framework spins up the right MCP servers automatically.\n- **Deploy anywhere** \u2014 `zibby deploy` pushes to Zibby Cloud with an API trigger; or self-host with `zibby start`.\n- **State accumulation** \u2014 each node's validated output is stored under its name in `state` (e.g., `state.classify_ticket`), so downstream nodes can reference upstream results.\n\n### What is a workflow?\nA directed graph of nodes (AI agent steps) connected by edges. Each node has:\n- `name` \u2014 unique identifier (snake_case)\n- `prompt` \u2014 function that receives state and returns the prompt string sent to the agent\n- `outputSchema` \u2014 Zod schema defining the structured output the agent must return\n- `skills` (optional) \u2014 array of MCP skill IDs the node needs (e.g., `SKILLS.BROWSER`, `SKILLS.GITHUB`)\n- `timeout` (optional) \u2014 max execution time in ms (default: 300000)\n- `model` (optional) \u2014 override the model for this node (e.g., `'claude-opus-4'`)\n\n### File structure\n```\n.zibby/workflows/<name>/\n\u251C\u2500\u2500 graph.mjs          \u2014 WorkflowAgent subclass with buildGraph()\n\u251C\u2500\u2500 nodes/\n\u2502   \u251C\u2500\u2500 index.mjs      \u2014 barrel export for all nodes\n\u2502   \u2514\u2500\u2500 <node>.mjs     \u2014 one file per node\n\u2514\u2500\u2500 workflow.json       \u2014 manifest (name, description, triggers)\n```\n\n### Node pattern\n```javascript\nimport { z, SKILLS } from '@zibby/core';\n\nconst OutputSchema = z.object({\n  summary: z.string().describe('Brief summary'),\n  items: z.array(z.string()).describe('List of extracted items'),\n  needsReview: z.boolean().describe('Whether a human should review this'),\n});\n\nexport const myNode = {\n  name: 'my_node',\n  skills: [SKILLS.GITHUB],  // optional \u2014 framework injects MCP servers\n  timeout: 120000,           // optional \u2014 2 min timeout\n  prompt: (state) => \\`You are analyzing a pull request.\n\nInput:\n\\${JSON.stringify(state.input || {}, null, 2)}\n\nReturn a JSON object matching the schema.\\`,\n  outputSchema: OutputSchema,\n};\n```\n\n### Graph pattern\n```javascript\nimport { WorkflowAgent, WorkflowGraph } from '@zibby/core';\nimport { classifyNode, routeNode } from './nodes/index.mjs';\n\nexport class MyWorkflow extends WorkflowAgent {\n  buildGraph() {\n    const graph = new WorkflowGraph();\n    graph.addNode('classify', classifyNode);\n    graph.addNode('route', routeNode);\n    graph.setEntryPoint('classify');\n    graph.addEdge('classify', 'route');\n    graph.addEdge('route', 'END');\n    return graph;\n  }\n\n  async onComplete(result) {\n    // Post-execution hook \u2014 save artifacts, notify, etc.\n    console.log('Workflow complete:', result.success);\n  }\n}\n```\n\nConditional edges: `graph.addConditionalEdges('node', (state) => state.node.priority === 'high' ? 'escalate' : 'notify')`\n\n### Available SKILLS constants\nImport from `@zibby/core`: `SKILLS.BROWSER`, `SKILLS.MEMORY`, `SKILLS.GITHUB`, `SKILLS.JIRA`, `SKILLS.SLACK`, `SKILLS.RUNNER`\n\n### Deep documentation\nCall `explore_framework_docs` to read detailed framework docs on demand. Use it for:\n- Advanced patterns (middleware, parallel nodes, state schemas)\n- Deployment & cloud triggers\n- CLI commands reference\n- Integration details (Jira, GitHub, etc.)\nCall with no arguments to see all available topics.\n\n### How to use the builder tools\n1. For complex workflows, call `explore_framework_docs(\"custom-workflows\")` first to learn advanced patterns.\n2. Ask the user what their workflow should do, what input it receives, and what steps are needed.\n3. Call `design_workflow` with the structured spec for the user to review.\n4. Once approved, call `build_workflow` to generate real code on disk (uses the configured agent for high-quality code generation).\n5. Remind the user: `zibby start <name>` to test locally, `zibby deploy <name> --project <id>` to deploy to cloud, `zibby logs --workflow <name>` to tail logs.\n\n### Important\n- Each node prompt should be detailed and specific \u2014 tell the AI agent exactly what to do and what format to return.\n- Zod schemas MUST use .describe() on every field so the agent knows what each field means.\n- Node names must be snake_case (e.g., classify_ticket, generate_report).\n- Workflow names must be kebab-case (e.g., ticket-triage, pr-review).\n- State flows through: each node's validated output is stored under its name in state (e.g., state.classify_ticket).\n- Downstream nodes reference upstream outputs in their prompt function (e.g., \\`\\${JSON.stringify(state.classify_ticket, null, 2)}\\`).\n- Nodes can declare skills to get MCP tool access \u2014 the framework handles server lifecycle automatically.";
+export {};

package/docs/apps/agent-ops.md

@@ -19,7 +19,7 @@ This is the structural difference between "deploy button on a VM" and **Zibby**.
 | **Upgrade orchestration** | on schedule | When a new app version lands in the catalog, agent-ops can run the in-place upgrade on a cron you set. |
 | **Activity log** | every action | One row in the app's "Agent activity" tab, with structured fields you can grep / chart. |
 
-Every action lands in DynamoDB as an `app-runs` record — queryable by anything from a workflow node to a Grafana dashboard.
+Every action lands in DynamoDB as an `app-runs` record — queryable by anything from an agent node to a Grafana dashboard.
 
 ## See it in action
 
@@ -85,20 +85,20 @@ Per-instance agent-ops behavior is tunable via env vars (set on the app instance
 | `AGENT_OPS_AUTO_UPGRADE` | `false` | If `true`, upgrade automatically when catalog publishes a new version |
 | `AGENT_OPS_NOTIFY_WEBHOOK` | — | URL to POST run records to (any HTTPS endpoint — your own backend, n8n, etc.) |
 
-`AGENT_OPS_NOTIFY_WEBHOOK` is how you wire agent-ops into your existing observability stack — fire every run record into your team's #ops Slack via a workflow trigger, into Datadog via their webhook receiver, or into your own database.
+`AGENT_OPS_NOTIFY_WEBHOOK` is how you wire agent-ops into your existing observability stack — fire every run record into your team's #ops Slack via an agent trigger, into Datadog via their webhook receiver, or into your own database.
 
-## Hooking agent-ops into a workflow
+## Hooking agent-ops into an agent
 
-The most powerful pattern: a Zibby workflow that runs **on agent-ops events**.
+The most powerful pattern: a Zibby agent that runs **on agent-ops events**.
 
-Example: when an `oom_recovery` fires, run a workflow that pulls the container's last-100-lines, classifies the crash, and pages whoever owns this app:
+Example: when an `oom_recovery` fires, run an agent that pulls the container's last-100-lines, classifies the crash, and pages whoever owns this app:
 
 ```bash
 zibby app env set a1b2c3d4 \
   AGENT_OPS_NOTIFY_WEBHOOK=https://api-prod.zibby.app/v1/workflows/<wf-uuid>/trigger
 ```
 
-The workflow receives the run record as `input`, can call back to `zibby app logs` / `zibby app status`, and decides what to do. Agent-ops + workflows compose into a self-operating fleet — humans only get pinged for genuinely novel failure modes.
+The agent receives the run record as `input`, can call back to `zibby app logs` / `zibby app status`, and decides what to do. Agent-ops + agents compose into a self-operating fleet — humans only get pinged for genuinely novel failure modes.
 
 ## Upgrade orchestration
 

package/docs/apps/deploy.md

@@ -16,7 +16,7 @@ npm install -g @zibby/cli
 zibby login                # OAuth in browser, saves session to ~/.zibby/config.json
 ```
 
-You also need a project. If you don't have one yet, deploy a workflow first or create one in the [Zibby dashboard](https://studio.zibby.dev) — apps are scoped to projects so per-instance EFS volumes can be isolated per team.
+You also need a project. If you don't have one yet, deploy an agent first or create one in the [Zibby dashboard](https://studio.zibby.dev) — apps are scoped to projects so per-instance EFS volumes can be isolated per team.
 
 ## Browse the catalog
 

package/docs/apps/index.md

@@ -42,7 +42,7 @@ Both are pillars of Zibby Cloud. Pick by **how long the thing needs to run**:
 | Persistence | Session JSONL + S3 artifacts | Encrypted-at-rest EFS volume |
 | Best for | "When ticket lands, classify it" | "Host Grafana for the team" |
 
-If you find yourself wanting to **run an open-source web app behind a stable URL**, that's an App. If you want **agent-driven business logic that fires on events**, that's an [Agent](../recipes/) (a workflow graph under the hood).
+If you find yourself wanting to **run an open-source web app behind a stable URL**, that's an App. If you want **agent-driven business logic that fires on events**, that's an [Agent](../recipes/).
 
 ## What you get with every app
 

package/docs/apps/managing.md

@@ -79,7 +79,7 @@ This picks up whatever's currently in your workspace credentials (set via [Setti
 
 ## ENV vars
 
-Every app instance has a per-instance encrypted env-var bag, same shape as workflow env. Use it for per-instance config (e.g. `N8N_ENCRYPTION_KEY`, `DATABASE_URL` pointing at an external RDS).
+Every app instance has a per-instance encrypted env-var bag, same shape as agent env. Use it for per-instance config (e.g. `N8N_ENCRYPTION_KEY`, `DATABASE_URL` pointing at an external RDS).
 
 Set via the dashboard (Apps → instance → ENV tab) or via CLI:
 

package/docs/cli-reference.md

@@ -5,22 +5,22 @@ title: CLI Reference
 
 # CLI Reference
 
-Every command lives under `zibby workflow <verb>` for consistency. The bare top-level forms (`zibby start`, `zibby deploy`, `zibby trigger`, `zibby logs`, `zibby g workflow`) are kept as backward-compat aliases — they call the same handlers — but new code should use the namespaced forms.
+Every command lives under `zibby agent <verb>` for consistency. The bare top-level forms (`zibby start`, `zibby deploy`, `zibby trigger`, `zibby logs`) are kept as backward-compat aliases — they call the same handlers — but new code should use the namespaced forms.
 
-## Workflow commands
+## Agent commands
 
 | Command | What it does |
 |---|---|
-| [`zibby workflow new <name>`](#workflow-new) | Scaffold a new custom workflow under `.zibby/workflows/<name>/`. |
-| [`zibby workflow run <name>`](#workflow-run) | One-shot local execution. Same input flags as `trigger`. |
-| [`zibby workflow list`](#workflow-list) | List local + deployed workflows. |
-| [`zibby workflow deploy [name]`](#workflow-deploy) | Deploy to Zibby Cloud. Interactive picker if name omitted. |
-| [`zibby workflow trigger [uuid]`](#workflow-trigger) | Run a deployed workflow remotely. UUID is canonical. |
-| [`zibby workflow logs [uuid] -t`](#workflow-logs) | Tail logs from a run, Heroku-style. |
-| [`zibby workflow download <uuid>`](#workflow-download) | Pull a deployed workflow back to local. Edit + redeploy. |
-| [`zibby workflow delete <uuid>`](#workflow-delete) | Delete a deployed workflow. |
-| [`zibby workflow start <name>`](#workflow-start) | Long-lived dev server (Studio integration). Most users want `run`. |
-| [`zibby workflow env <verb>`](#workflow-env) | Manage per-workflow encrypted env vars: `list`, `set`, `unset`, `push`. |
+| [`zibby agent new <name>`](#agent-new) | Scaffold a new custom agent under `.zibby/workflows/<name>/`. |
+| [`zibby agent run <name>`](#agent-run) | One-shot local execution. Same input flags as `trigger`. |
+| [`zibby agent list`](#agent-list) | List local + deployed agents. |
+| [`zibby agent deploy [name]`](#agent-deploy) | Deploy to Zibby Cloud. Interactive picker if name omitted. |
+| [`zibby agent trigger [uuid]`](#agent-trigger) | Run a deployed agent remotely. UUID is canonical. |
+| [`zibby agent logs [uuid] -t`](#agent-logs) | Tail logs from a run, Heroku-style. |
+| [`zibby agent download <uuid>`](#agent-download) | Pull a deployed agent back to local. Edit + redeploy. |
+| [`zibby agent delete <uuid>`](#agent-delete) | Delete a deployed agent. |
+| [`zibby agent start <name>`](#agent-start) | Long-lived dev server (Studio integration). Most users want `run`. |
+| [`zibby agent env <verb>`](#agent-env) | Manage per-agent encrypted env vars: `list`, `set`, `unset`, `push`. |
 
 Plus the test recipe + memory + project setup:
 
@@ -28,8 +28,8 @@ Plus the test recipe + memory + project setup:
 |---|---|
 | [`zibby test [spec]`](#test) | Run a test spec (or inline string). Drives the browser via Cursor / Claude / Codex / Gemini. |
 | [`zibby memory <verb>`](#memory) | Local + remote test-memory DB: `init`, `stats`, `cost`, `compact`, `reset`, `pull`, `push`, `remote …`. |
-| [`zibby init [project]`](#init) | Bootstrap a Zibby project (config + creds). `-t <template>` to also scaffold a workflow. |
-| [`zibby template <verb>`](#template) | List or add workflow templates: `list`, `add <name>`. |
+| [`zibby init [project]`](#init) | Bootstrap a Zibby project (config + creds). `-t <template>` to also scaffold an agent. |
+| [`zibby template <verb>`](#template) | List or add agent templates: `list`, `add <name>`. |
 
 Auth + admin:
 
@@ -40,10 +40,10 @@ Auth + admin:
 | `zibby status` | Show current auth state. |
 | `zibby list` | List projects + API tokens you have access to. |
 
-## workflow new {#workflow-new}
+## agent new {#agent-new}
 
 ```bash
-zibby workflow new [name]
+zibby agent new [name]
 ```
 
 Scaffolds `.zibby/workflows/<name>/` with a starter `graph.mjs`, `nodes/example.mjs`, `package.json`, and `workflow.json` manifest. Auto-runs `npm install` in the new folder unless `--skip-install`.
@@ -52,15 +52,15 @@ Options:
 - `--skip-install` — skip `npm install`
 - If `name` is omitted, the CLI generates one (`zealous-otter`, etc.)
 
-## workflow run {#workflow-run}
+## agent run {#agent-run}
 
 ```bash
-zibby workflow run <workflow-name>
+zibby agent run <agent-name>
 ```
 
 Loads `graph.mjs`, instantiates the entry class, runs the graph **once** in-process, prints results, and exits. Output → `.zibby/output/sessions/<sessionId>/`.
 
-Mirrors `zibby workflow trigger` so the same input flags work locally and in the cloud — flip the verb and the project, and your local dev loop is exactly the same call shape your CI/CD uses.
+Mirrors `zibby agent trigger` so the same input flags work locally and in the cloud — flip the verb and the project, and your local dev loop is exactly the same call shape your CI/CD uses.
 
 Options:
 - `-p, --param <key=value>` — input param (repeatable, highest precedence). Example: `-p ticket=BUG-123 -p priority=high`
@@ -69,40 +69,40 @@ Options:
 
 Examples:
 ```bash
-zibby workflow run my-pipeline
-zibby workflow run my-pipeline -p ticket=BUG-123
-zibby workflow run my-pipeline --input '{"ticket":"BUG-123","priority":"high"}'
-zibby workflow run my-pipeline --input-file payload.json -p priority=urgent
+zibby agent run my-agent
+zibby agent run my-agent -p ticket=BUG-123
+zibby agent run my-agent --input '{"ticket":"BUG-123","priority":"high"}'
+zibby agent run my-agent --input-file payload.json -p priority=urgent
 ```
 
-## workflow start {#workflow-start}
+## agent start {#agent-start}
 
 ```bash
-zibby workflow start <workflow-name>
+zibby agent start <agent-name>
 ```
 
-Long-lived local dev server (default port 3848). Listens on `POST /trigger` for input payloads and runs the workflow in-process. Used today by the Studio desktop app — for plain CLI use, prefer `workflow run`.
+Long-lived local dev server (default port 3848). Listens on `POST /trigger` for input payloads and runs the agent in-process. Used today by the Studio desktop app — for plain CLI use, prefer `agent run`.
 
 Options:
 - `-p, --port <port>` — override the default port (3848)
 
-## workflow list {#workflow-list}
+## agent list {#agent-list}
 
 ```bash
-zibby workflow list
+zibby agent list
 ```
 
-Shows both local workflows (folders under `.zibby/workflows/`) and deployed ones (from cloud, scoped to projects you have access to). Output is a table with UUID, Name, Project, Version. `-` in any column means "not applicable" (e.g. local-only workflows have no UUID yet).
+Shows both local agents (folders under `.zibby/workflows/`) and deployed ones (from cloud, scoped to projects you have access to). Output is a table with UUID, Name, Project, Version. `-` in any column means "not applicable" (e.g. local-only agents have no UUID yet).
 
 Options:
 - `--local-only` — skip the cloud query
 - `--remote-only` — skip the local scan
 - `--project <id>` — filter to one project
 
-## workflow deploy {#workflow-deploy}
+## agent deploy {#agent-deploy}
 
 ```bash
-zibby workflow deploy [workflow-name]
+zibby agent deploy [agent-name]
 ```
 
 Two phases:
@@ -114,16 +114,16 @@ After success, the CLI writes `.zibby/workflows/<name>/.zibby-deploy.json` with
 Options:
 - `--project <id>` — skip the project picker
 - `--api-key <key>` — auth via API key (or set `ZIBBY_API_KEY`)
-- `--env <path>` — sync a `.env` file into per-workflow env vars after deploy. Repeatable (later files override). See [Per-workflow env vars](./cloud/env-vars).
+- `--env <path>` — sync a `.env` file into per-agent env vars after deploy. Repeatable (later files override). See [Per-agent env vars](./cloud/env-vars).
 - `--verbose` — show raw CodeBuild logs during the bundle build
 
-## workflow trigger {#workflow-trigger}
+## agent trigger {#agent-trigger}
 
 ```bash
-zibby workflow trigger <uuid>
+zibby agent trigger <uuid>
 ```
 
-UUID is required (or omit for interactive picker). Names aren't accepted — pass the UUID from `.zibby-deploy.json` or `workflow list`.
+UUID is required (or omit for interactive picker). Names aren't accepted — pass the UUID from `.zibby-deploy.json` or `agent list`.
 
 Options:
 - `-p, --param <key=value>` — input param (repeatable, highest precedence)
@@ -132,14 +132,14 @@ Options:
 - `--idempotency-key <key>` — prevent duplicate executions
 - `--api-key <key>` — auth via API key
 
-## workflow logs {#workflow-logs}
+## agent logs {#agent-logs}
 
 ```bash
-zibby workflow logs <uuid>          # dump latest run
-zibby workflow logs <uuid> -t       # tail live (Heroku-style)
+zibby agent logs <uuid>          # dump latest run
+zibby agent logs <uuid> -t       # tail live (Heroku-style)
 ```
 
-When `-t` is set and the workflow finishes, the stream waits for the next trigger of the same workflow and auto-switches to streaming it. Ctrl+C to exit.
+When `-t` is set and the agent finishes, the stream waits for the next trigger of the same agent and auto-switches to streaming it. Ctrl+C to exit.
 
 Options:
 - `-t, --follow` — live tail
@@ -147,43 +147,43 @@ Options:
 - `--all --workflow <name>` — interleaved logs from all runs (requires `--workflow`)
 - `--api-key <key>` — auth via API key
 
-**Storage & retention.** Live logs are kept in CloudWatch for 30 days. Beyond that, the per-run session folder (uploaded to S3 at the end of every execution) is the long-term archive — pull it back with `zibby workflow download <uuid>`.
+**Storage & retention.** Live logs are kept in CloudWatch for 30 days. Beyond that, the per-run session folder (uploaded to S3 at the end of every execution) is the long-term archive — pull it back with `zibby agent download <uuid>`.
 
-## workflow env {#workflow-env}
+## agent env {#agent-env}
 
-Per-workflow encrypted env vars — KMS-stored on the workflow record, injected into the Fargate task at trigger time. Workflow env wins over project secrets on conflict.
+Per-agent encrypted env vars — KMS-stored on the agent record, injected into the Fargate task at trigger time. Agent env wins over project secrets on conflict.
 
 ```bash
-zibby workflow env list <uuid>                       # show key names (no values)
-zibby workflow env set <uuid> ANTHROPIC_API_KEY=sk-…  # add or rotate one
-zibby workflow env unset <uuid> OLD_KEY               # remove one
-zibby workflow env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
+zibby agent env list <uuid>                       # show key names (no values)
+zibby agent env set <uuid> ANTHROPIC_API_KEY=sk-…  # add or rotate one
+zibby agent env unset <uuid> OLD_KEY               # remove one
+zibby agent env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
 ```
 
 `push` accepts repeatable `--file` (later files override). `list` only ever returns key names — values never leave the encrypted blob.
 
-The shortcut for first-time setup is `zibby workflow deploy --env .env`, which runs `push` automatically against the new UUID. Full guide: [Per-workflow env vars](./cloud/env-vars).
+The shortcut for first-time setup is `zibby agent deploy --env .env`, which runs `push` automatically against the new UUID. Full guide: [Per-agent env vars](./cloud/env-vars).
 
-## workflow download {#workflow-download}
+## agent download {#agent-download}
 
 ```bash
-zibby workflow download <uuid>
+zibby agent download <uuid>
 ```
 
-Pulls the deployed workflow's sources back into `.zibby/workflows/<name>/`, including the `.zibby-deploy.json` manifest. Useful when collaborators need the source from cloud.
+Pulls the deployed agent's sources back into `.zibby/workflows/<name>/`, including the `.zibby-deploy.json` manifest. Useful when collaborators need the source from cloud.
 
 Options:
-- `--type <type>` — for built-in workflows (`analysis`, `implementation`, `run_test`)
+- `--type <type>` — for built-in agents (`analysis`, `implementation`, `run_test`)
 - `--output <dir>` — alternate output base
 - `--include-default` — pull the built-in default graph if no custom one exists
 
-## workflow delete {#workflow-delete}
+## agent delete {#agent-delete}
 
 ```bash
-zibby workflow delete <uuid>
+zibby agent delete <uuid>
 ```
 
-Removes the workflow from cloud (and its trigger URL). Local files are not touched.
+Removes the agent from cloud (and its trigger URL). Local files are not touched.
 
 ## test {#test}
 
@@ -240,10 +240,10 @@ zibby init [project-name]
 zibby init -t browser-test-automation   # also scaffold the test recipe
 ```
 
-Bare init by default — writes `.zibby.config.mjs`, sets up agent credentials, configures memory. Pass `-t <template>` to also scaffold a workflow template into `.zibby/`.
+Bare init by default — writes `.zibby.config.mjs`, sets up agent credentials, configures memory. Pass `-t <template>` to also scaffold an agent template into `.zibby/`.
 
 Common options:
-- `-t, --template <name>` — workflow template to scaffold (see `zibby template list`). Default: none (config + creds only).
+- `-t, --template <name>` — agent template to scaffold (see `zibby template list`). Default: none (config + creds only).
 - `--agent <claude|cursor|codex|gemini>` — pick the agent up front instead of prompting
 - `--memory-backend <mem0|dolt>` — memory backend (default: `mem0` — semantic vector memory, billed through the agent run in cloud, falls back to `dolt` if the embedding proxy is unavailable; pass `dolt` for self-contained structured memory — see [Chat memory](./skills/chat-memory.md))
 - `--skip-install` / `--skip-memory` — skip `npm install` / skip memory setup
@@ -258,7 +258,7 @@ zibby template list             # see what's available
 zibby template add <name>       # copy template into .zibby/ (overwrites = doubles as update)
 ```
 
-Templates are starter workflow scaffolds. `add` overwrites existing files in place — use it to upgrade an outdated agent helpers block, or to grab a recipe you didn't pick at `init` time.
+Templates are starter agent scaffolds. `add` overwrites existing files in place — use it to upgrade an outdated agent helpers block, or to grab a recipe you didn't pick at `init` time.
 
 `zibby template add zibby-workflow-claude` (or `-cursor`, `-codex`) refreshes the per-agent guidance files emitted by this template — the `<!-- zibby-template-version: N -->` markers make the upgrade idempotent.
 
@@ -442,20 +442,20 @@ Drains the ECS service, deletes the task definition revision, removes the ALB li
 | `ZIBBY_API_KEY` | API key for non-interactive auth (CI). Preferred over saved session. |
 | `ZIBBY_PROJECT_ID` | Default project for commands that take `--project` |
 | `AGENT_TYPE` | Default agent strategy when no per-node override and no project default |
-| `ZIBBY_DEPLOY_VERBOSE=1` | Same as `--verbose` on `workflow deploy` |
+| `ZIBBY_DEPLOY_VERBOSE=1` | Same as `--verbose` on `agent deploy` |
 | `ZIBBY_SESSION_LOG=1` | Re-enable the diagnostic `[zibby:session]` log line in run output |
 | `ZIBBY_RUN_DIAG=1` | Cloud runtime: dump per-copy `agent-workflow` registry state |
 | `ZIBBY_DEBUG=true` | Verbose debug logs from the framework |
 
 ## Legacy aliases
 
-These still work and route to the same handlers, but new code should use the `zibby workflow <verb>` form:
+These still work and route to the same handlers, but new code should use the `zibby agent <verb>` form. The `zibby workflow <verb>` namespace also remains a full alias for `zibby agent <verb>`:
 
 | Legacy | Canonical |
 |---|---|
-| `zibby g workflow <name>` | `zibby workflow new <name>` |
-| `zibby start <name>` | `zibby workflow start <name>` |
-| `zibby run <name>` | `zibby workflow run <name>` |
-| `zibby deploy [name]` | `zibby workflow deploy [name]` |
-| `zibby trigger <uuid>` | `zibby workflow trigger <uuid>` |
-| `zibby logs <uuid>` | `zibby workflow logs <uuid>` |
+| `zibby g workflow <name>` | `zibby agent new <name>` |
+| `zibby start <name>` | `zibby agent start <name>` |
+| `zibby run <name>` | `zibby agent run <name>` |
+| `zibby deploy [name]` | `zibby agent deploy [name]` |
+| `zibby trigger <uuid>` | `zibby agent trigger <uuid>` |
+| `zibby logs <uuid>` | `zibby agent logs <uuid>` |