@zibby/skills 0.1.32 → 0.1.34

package/docs/get-started/use-from-agents.md

@@ -6,13 +6,13 @@ pagination_prev: get-started/trigger-and-logs
 
 # Use Zibby from Claude Code, Cursor, Codex, or Gemini
 
-Zibby ships an MCP (Model Context Protocol) server — [`@zibby/mcp-cli`](../packages/mcp-cli). Add it once to your agent's config and Zibby becomes a first-class tool the agent can call directly from chat. Deploy workflows, trigger runs, tail logs — all without leaving your editor.
+Zibby ships an MCP (Model Context Protocol) server — [`@zibby/mcp-cli`](../packages/mcp-cli). Add it once to your agent's config and Zibby becomes a first-class tool the agent can call directly from chat. Deploy agents, trigger runs, tail logs — all without leaving your editor.
 
 ```
 You:    Deploy the browser-test template to my Playhouse project, then run it.
-Agent:  → zibby_scaffold_workflow
-        → zibby_deploy_workflow
-        → zibby_trigger_workflow
+Agent:  → zibby_scaffold_agent
+        → zibby_deploy_agent
+        → zibby_trigger_agent
         → "Done. Job a23e… completed in 47s, 0 failures."
 ```
 
@@ -109,14 +109,14 @@ Login state lives in `~/.zibby/config.json` (mode `0600`) — the same file the
 
 | Read-only | Write |
 |---|---|
-| List projects | Scaffold a workflow from an official template |
-| List official templates | Deploy a workflow to a project |
-| List workflows (local + remote) | Trigger a deployed workflow |
-| Show login status | Run a workflow locally (debug) |
-| Fetch logs from a run | Download a deployed workflow (with explicit user confirmation) |
-| Static-validate a workflow | |
+| List projects | Scaffold an agent from an official template |
+| List official templates | Deploy an agent to a project |
+| List agents (local + remote) | Trigger a deployed agent |
+| Show login status | Run an agent locally (debug) |
+| Fetch logs from a run | Download a deployed agent (with explicit user confirmation) |
+| Static-validate an agent | |
 
-**Destructive operations stay out of the agent's hands** — workflow delete, env-var changes, schedule mutation, and credential management require you to run `zibby` in a terminal. Two-stage authorization for anything that could surprise you.
+**Destructive operations stay out of the agent's hands** — agent delete, env-var changes, schedule mutation, and credential management require you to run `zibby` in a terminal. Two-stage authorization for anything that could surprise you.
 
 See the [`@zibby/mcp-cli` package reference](../packages/mcp-cli) for the full tool list and security model.
 
@@ -131,22 +131,22 @@ Agent:  → zibby_list_templates
          - code-analysis: Jira ticket → analyze → generate code → emit tests
          - generate-test-cases: code diff → prioritized AI-runnable test specs"
 
-You:    Scaffold generate-test-cases into a new workflow called "release-tests" in my Playhouse project.
+You:    Scaffold generate-test-cases into a new agent called "release-tests" in my Playhouse project.
 
 Agent:  → zibby_list_projects                       (resolves "Playhouse" → projectId)
-        → zibby_scaffold_workflow name=release-tests template=generate-test-cases
-        → zibby_validate_workflow name=release-tests
+        → zibby_scaffold_agent name=release-tests template=generate-test-cases
+        → zibby_validate_agent name=release-tests
         "Scaffolded and validated. Ready to deploy."
 
 You:    Deploy it.
 
-Agent:  → zibby_deploy_workflow name=release-tests projectId=…
+Agent:  → zibby_deploy_agent name=release-tests projectId=…
         "Deployed v1 — UUID 33039db5-2f32-4094-9841-317bc56a88c9."
 
 You:    Run it against this PR diff: ‹pastes diff›
 
-Agent:  → zibby_trigger_workflow uuid=33039db5… input={diff: "...", changedFiles: [...]}
-        → zibby_workflow_logs jobId=c62e97a4… lines=100
+Agent:  → zibby_trigger_agent uuid=33039db5… input={diff: "...", changedFiles: [...]}
+        → zibby_agent_logs jobId=c62e97a4… lines=100
         "Run completed in 1m 23s. Generated 7 test specs (4 Critical, 2 High, 1 Medium)."
 ```
 

package/docs/get-started/your-first-workflow.md

@@ -1,30 +1,33 @@
 ---
 sidebar_position: 2
-title: 2. Your first workflow
+title: 2. Your first agent
 pagination_prev: get-started/install
 pagination_next: get-started/run-locally
 ---
 
-# Scaffold a workflow
+# Scaffold your first agent
+
+An **Agent** is a deployed automation. Scaffold one with the CLI with the `zibby agent` CLI:
 
 ```bash
-zibby workflow new my-pipeline
+zibby agent new my-agent
+# zibby agent new my-agent   # alias — identical
 ```
 
 This creates:
 
 ```
-.zibby/workflows/my-pipeline/
+.zibby/workflows/my-agent/
 ├── graph.mjs         # the workflow definition (entry point)
 ├── nodes/
 │   └── example.mjs   # a sample node
-├── package.json      # workflow's own deps (each workflow is a self-contained npm project)
+├── package.json      # agent's own deps (each agent is a self-contained npm project)
 └── workflow.json     # manifest (workflow name, entry class)
 ```
 
 If `.zibby/workflows/` doesn't exist yet, the scaffold creates it. If you have a `.zibby.config.mjs` with a custom `paths.workflows`, the scaffold respects it.
 
-The first time you run this in a fresh directory, you'll be asked where to keep workflows (default: `.zibby/workflows`). The CLI also runs `npm install` inside the new workflow folder so deps are ready.
+The first time you run this in a fresh directory, you'll be asked where to keep agents (default: `.zibby/workflows`). The CLI also runs `npm install` inside the new agent folder so deps are ready.
 
 ## What's in graph.mjs
 
@@ -61,6 +64,6 @@ The shape is:
 
 ## Picking the agent
 
-Each node can specify its own agent via `agent: 'cursor' | 'claude' | 'codex' | 'gemini' | 'assistant'`. If you omit it, the workflow falls back to the project default (set in `.zibby.config.mjs` or `AGENT_TYPE` env var).
+Each node can specify its own agent via `agent: 'cursor' | 'claude' | 'codex' | 'gemini' | 'assistant'`. If you omit it, the agent falls back to the project default (set in `.zibby.config.mjs` or `AGENT_TYPE` env var).
 
 → Next: [Run it locally](./run-locally)

package/docs/integrations/gitlab.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 5
+title: GitLab Integration
+---
+
+# GitLab Integration
+
+Connect a **self-hosted GitLab** instance (or GitLab SaaS) so your agents can read repos, merge requests, issues, and pipelines. GitLab uses a **Personal Access Token**.
+
+## How It Works
+
+You provide your GitLab instance URL and a Personal Access Token. The `gitlab` skill then exposes GitLab's API to any node that declares it. Outbound calls to a firewalled self-hosted instance can be pinned to a [dedicated egress IP](../cloud/dedicated-egress.md).
+
+## Connect GitLab
+
+1. In GitLab, go to **User Settings → Access Tokens** and create a Personal Access Token with the `read_api` and `read_repository` scopes (form `glpat-...`)
+2. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect GitLab**
+3. Enter your **GitLab Instance URL** (e.g. `https://gitlab.company.com`)
+4. Paste the **Personal Access Token**
+5. Click **Connect** — Zibby validates both before saving
+
+| Field | Required | Notes |
+|---|---|---|
+| GitLab Instance URL | Yes | Your instance, e.g. `https://gitlab.company.com` (or `https://gitlab.com`) |
+| Personal Access Token | Yes | `glpat-...` with `read_api` + `read_repository` scopes |
+
+## What Agents Can Do
+
+Nodes that attach the [`gitlab` skill](../skills/index.md) get tools for repos, merge requests, issues, and pipelines, against either self-hosted GitLab or GitLab SaaS.
+
+## Reference keys (SDK / CLI)
+
+When running agents directly, the connector reads `GITLAB_TOKEN` (and a base URL for self-hosted instances) from the environment.
+
+## Firewalled instances
+
+If your GitLab is behind a firewall, add the [dedicated egress IP addon](../cloud/dedicated-egress.md) so all outbound traffic comes from one whitelistable IP.
+
+## Troubleshooting
+
+**"401 Unauthorized"** — regenerate the token with `read_api` + `read_repository` scopes; expired or under-scoped tokens fail here.
+
+**"Could not reach instance"** — confirm the instance URL is reachable from Zibby's egress IP and that it points at the GitLab base URL, not a project page.

package/docs/integrations/lark.md

@@ -0,0 +1,41 @@
+---
+sidebar_position: 8
+title: Lark Integration
+---
+
+# Lark Integration
+
+Connect a Lark (Feishu) self-built app so your agents can send messages, reply, list chats, and read chat history. Lark uses an **App ID + App Secret**.
+
+## How It Works
+
+You create a self-built app in the Lark Developer Console and paste its App ID and App Secret into Zibby. Optionally add a Verification Token and Encrypt Key if you want inbound Lark events to trigger Zibby agents. The `lark` skill then exposes Lark's API to any node that declares it.
+
+## Connect Lark
+
+1. In the Lark Developer Console, open your self-built app and go to **Credentials & Basic Info**
+2. Copy the **App ID** (`cli_...`) and **App Secret**
+3. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect Lark**
+4. Paste the App ID and App Secret
+5. (Optional) Add the **Verification Token** and **Encrypt Key** from **Event Subscriptions** if you want inbound events
+
+| Field | Required | Notes |
+|---|---|---|
+| App ID | Yes | `cli_...` from Credentials & Basic Info |
+| App Secret | Yes | From Credentials & Basic Info |
+| Verification Token | No | Required only for inbound events (Event Subscriptions) |
+| Encrypt Key | No | Only if Lark-side event encryption is enabled |
+
+## What Agents Can Do
+
+Nodes that attach the [`lark` skill](../skills/lark.md) get `lark_send_message`, `lark_reply`, `lark_list_chats`, and `lark_get_chat_history` — used by routing recipes like [Sentry triage](../recipes/sentry-triage.md) as a Slack alternative.
+
+## Inbound events
+
+Adding the Verification Token (and Encrypt Key, if enabled) lets Lark events fire your Zibby agents. Leave them blank for outbound-only (notifications).
+
+## Troubleshooting
+
+**"Invalid App Secret"** — regenerate the secret in the Developer Console and reconnect.
+
+**Bot can't post to a chat** — the app must be added to the target chat/group and have the messaging permission scopes granted in the console.

package/docs/integrations/linear.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 3
+title: Linear Integration
+---
+
+# Linear Integration
+
+Connect Linear so your agents can read and update issues, comments, and workflow states. Linear uses a **personal API key** — no OAuth round-trip.
+
+## How It Works
+
+You paste a single Linear personal API key. Zibby validates it (by querying the authenticated viewer) before storing it, then the `linear` skill exposes Linear's API to any node that declares it.
+
+## Connect Linear
+
+1. In Linear, go to **Settings → Security & access → Personal API keys**
+2. Create a new key — it has the form `lin_api_...`
+3. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect Linear**
+4. Paste the key and click **Connect**
+
+That's it — one field. Zibby verifies the key against Linear's GraphQL API before saving.
+
+## What Agents Can Do
+
+Once connected, nodes that attach the [`linear` skill](../skills/index.md) get these tools:
+
+| Tool | What it does |
+|---|---|
+| `linear_list_issues` | List issues (filter by team, state, assignee, label) |
+| `linear_get_issue` | Fetch one issue with full detail |
+| `linear_add_comment` | Comment on an issue |
+| `linear_update_state` | Move an issue to a different workflow state |
+| `linear_list_teams` / `linear_list_states` / `linear_list_labels` | Resolve names → IDs for the calls above |
+
+## Reference key (SDK / CLI)
+
+When running agents directly (local or CI), the same connector reads from the `LINEAR_API_KEY` environment variable instead of the dashboard-stored credential.
+
+## Troubleshooting
+
+**"Invalid API key"** — regenerate the key in Linear (Settings → Security & access → Personal API keys) and reconnect. Keys are revoked when you remove them from Linear.
+
+**Agent can't find a team/state** — call `linear_list_teams` / `linear_list_states` first; Linear's API keys are scoped to whatever the issuing user can see.

package/docs/integrations/notion.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 9
+title: Notion Integration
+---
+
+# Notion Integration
+
+Connect a Notion workspace so your agents can read and write pages and databases — for example, publishing a rich digest as Notion blocks. Notion uses **OAuth** (workspace install).
+
+## How It Works
+
+You authorize Zibby against a Notion workspace via OAuth. Notion returns a long-lived bearer token (no refresh, no expiry) scoped to the pages and databases you grant. Zibby stores it encrypted with the workspace metadata. The report renderer then publishes structured digests as native Notion blocks.
+
+## Connect Notion
+
+1. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect** next to Notion
+2. You're redirected to Notion to authorize Zibby
+3. Select which pages/databases Zibby may access
+4. You're redirected back to Zibby — the card shows the connected workspace
+
+## What Agents Can Do
+
+Agents can render a `report` object straight to Notion blocks (`reportToNotionBlocks`) and publish it to a connected page or database — the same digest you can route to Slack or Lark. The `notify-notion` template is the shipped example.
+
+## Reference key (SDK / CLI)
+
+When running agents directly, the connector reads `NOTION_API_KEY` from the environment (a Notion internal-integration token works for the SDK path).
+
+## Troubleshooting
+
+**Agent can't see a page** — Notion access is page-scoped. Re-run the OAuth flow and grant the specific page/database, or share it with the integration from Notion's UI.
+
+**Write fails** — confirm the granted pages include write access; read-only grants can't create blocks.

package/docs/integrations/plane.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+title: Plane Integration
+---
+
+# Plane Integration
+
+Connect [Plane](https://plane.so) — the open-source project-management tool — so your agents can read and write projects, work items, cycles, modules, and comments. Plane uses an **API key**, not OAuth.
+
+## How It Works
+
+You provide three values: an API key, a workspace slug, and (optionally) a base URL. Zibby validates them (by listing the workspace's projects) before storing, then the `plane` skill talks to Plane's official MCP server.
+
+## Connect Plane
+
+1. In Plane, go to **Workspace Settings → API tokens** and create a personal API token (form `plane_api_...`)
+2. Note your **workspace slug** — it's the segment in your Plane URL (`app.plane.so/<workspace-slug>/...`)
+3. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect Plane**
+4. Paste the API key and workspace slug
+5. **Base URL** — leave blank for Plane Cloud (`https://api.plane.so`). For self-hosted or Zibby-hosted Plane, set it to your instance's API base.
+
+Zibby lists your workspace's projects to confirm the credentials work before saving.
+
+| Field | Required | Notes |
+|---|---|---|
+| API key | Yes | From Workspace Settings → API tokens |
+| Workspace slug | Yes | The `<slug>` in your Plane URL |
+| Base URL | No | Defaults to `https://api.plane.so` (Plane Cloud). Set for self-hosted. |
+
+## What Agents Can Do
+
+Nodes that attach the [`plane` skill](../skills/index.md) get tools for projects, work items, cycles, modules, epics, and comments, backed by Plane's official MCP server.
+
+## Reference keys (SDK / CLI)
+
+When running agents directly, the connector reads `PLANE_API_KEY`, `PLANE_WORKSPACE_SLUG`, and `PLANE_BASE_URL` from the environment.
+
+## Pairs well with hosted Plane
+
+Plane is also in the [Managed Apps catalog](../apps/index.md) — you can host a Plane instance on Zibby and point this connector at it via the **Base URL** field.
+
+## Troubleshooting
+
+**"Workspace not found"** — double-check the workspace slug matches the segment in your Plane URL exactly.
+
+**Self-hosted instance rejects the token** — confirm the **Base URL** points at the API base of your instance, not the web UI URL.

package/docs/integrations/sentry.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 6
+title: Sentry Integration
+---
+
+# Sentry Integration
+
+Connect a Sentry organization so your agents can list projects, list issues, and fetch issue detail — read-only. Sentry uses **OAuth 2.0 with PKCE**.
+
+## How It Works
+
+You authorize Zibby against your Sentry organization via OAuth (PKCE — no client secret). Once connected, the `sentry` skill exposes read-only Sentry tools to any node that declares it. This powers the [Sentry triage](../recipes/sentry-triage.md) agent.
+
+## Connect Sentry
+
+1. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect Sentry**
+2. You're redirected to Sentry to authorize Zibby
+3. Pick the organization to grant access to
+4. You're redirected back to Zibby
+
+## What Agents Can Do
+
+Nodes that attach the [`sentry` skill](../skills/sentry.md) get read-only tools:
+
+| Tool | What it does |
+|---|---|
+| `sentry_list_projects` | List projects in the connected organization |
+| `sentry_list_issues` | List issues (supports Sentry search syntax, sort, limit) |
+| `sentry_get_issue` | Detailed info for one issue by ID |
+
+Access is read-only by design — the triage agent reads issues and routes them via Slack/Lark rather than mutating Sentry.
+
+## See also
+
+- [Sentry skill reference](../skills/sentry.md) — full tool surface
+- [Sentry triage recipe](../recipes/sentry-triage.md) — the agent that consumes this connector
+
+## Troubleshooting
+
+**"Reconnect Sentry"** — the OAuth grant was revoked or expired. Go to Settings → Integrations and reconnect.
+
+**No issues returned** — check the project filter and that the org you authorized actually owns the project.

package/docs/integrations/slack.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 7
+title: Slack Integration
+---
+
+# Slack Integration
+
+Connect a Slack workspace so your agents can post messages, reply in threads, react, read history, and resolve users. Slack uses **OAuth (V2)** — one click, no token pasting.
+
+## How It Works
+
+You authorize the Zibby Slack app against your workspace. Slack returns a bot token (`xoxb-...`) that Zibby stores encrypted, along with the team ID/name. The `slack` skill then exposes Slack's API to any node that declares it.
+
+## Connect Slack
+
+1. In the Zibby dashboard, go to **Settings → Integrations** and click **Connect** next to Slack
+2. You're redirected to Slack to authorize the Zibby app and pick a workspace
+3. Approve the requested scopes
+4. You're redirected back to Zibby — the card shows the connected team name
+
+## What Agents Can Do
+
+Nodes that attach the [`slack` skill](../skills/slack.md) get tools to list channels, post and reply, react, read channel/thread history, and look up users (by email, search, usergroups). This powers routing in recipes like [Sentry triage](../recipes/sentry-triage.md), where the agent resolves an author email to a Slack user and DMs them.
+
+## Reference (SDK / CLI)
+
+When running agents directly, the connector reads the bot token and team ID from the environment.
+
+## Troubleshooting
+
+**Message not delivered** — the bot must be invited to private channels before it can post there.
+
+**User lookup returns nothing** — `slack_get_users` excludes bots and deactivated accounts; confirm the user is active in the workspace.

package/docs/intro.md

@@ -7,7 +7,9 @@ pagination_next: get-started/install
 
 # Zibby
 
-**The cloud pipeline for Claude Code, Cursor, Codex, and Gemini.** Compose them into structured workflows with Zod-validated handoff between nodes. Vendor-neutral. JavaScript-first.
+**The cloud platform for AI agents — built on Claude Code, Cursor, Codex, and Gemini.** Compose real coding-agent CLIs into structured agents with Zod-validated handoff between nodes, then deploy them to the cloud. Vendor-neutral. JavaScript-first.
+
+> An **Agent** is a deployed automation — a graph of coding-agent CLI calls with Zod-typed handoff between nodes. Build and ship one with the `zibby agent` CLI.
 
 ```
             ┌──────────┐    ┌──────────┐    ┌──────────┐
@@ -27,22 +29,24 @@ graph
 
 ## Try it now
 
+Get started in seconds:
+
 ```bash
 npm install -g @zibby/cli
-zibby init                          # bare init (config + creds; no template)
-zibby workflow new my-pipeline      # scaffold a custom workflow
-zibby workflow run my-pipeline      # run locally (one-shot)
+zibby init                       # bare init (config + creds; no template)
+zibby agent new my-agent         # scaffold a custom agent
+zibby agent run my-agent         # run locally (one-shot)
 
 zibby login
-zibby workflow deploy my-pipeline   # ship to cloud
-zibby workflow trigger <uuid>       # fire it
-zibby workflow logs <uuid> -t       # tail logs
+zibby agent deploy my-agent      # ship to cloud
+zibby agent trigger <uuid>       # fire it
+zibby agent logs <uuid> -t       # tail logs
 ```
 
-Want a starter recipe instead of a blank slate? Use `-t`:
+Want a ready-made agent instead of a blank slate? Browse the [Agent Marketplace](./recipes/) and use `-t`:
 
 ```bash
-zibby init -t browser-test-automation     # scaffold the test recipe at init time
+zibby init -t browser-test-automation     # scaffold a marketplace template at init time
 zibby template list                        # see what's available
 zibby template add <name>                  # add a template later (overwrites = doubles as update)
 ```
@@ -51,7 +55,7 @@ zibby template add <name>                  # add a template later (overwrites =
 
 ## What you get
 
-- **Multi-vendor** — mix Claude Code + Codex + Cursor + Gemini in one pipeline. Anthropic will never help you orchestrate Codex; multi-vendor neutrality is structural.
+- **Multi-vendor** — mix Claude Code + Codex + Cursor + Gemini in one agent. Anthropic will never help you orchestrate Codex; multi-vendor neutrality is structural.
 - **Schema-enforced handoff** — Zod validates every node's output before the next runs. No prompt-stuffing.
 - **Run anywhere** — local with hot reload, or cloud with Heroku-style bundles (~3s cold start).
 - **Session replay** — every run lands as on-disk JSONL + artifacts. Re-run any node via `--session <id> --node <name>`.
@@ -61,14 +65,14 @@ zibby template add <name>                  # add a template later (overwrites =
 
 ## Two product surfaces
 
-| | **Workflows** | **Apps** |
+| | **Agents** | **Apps** |
 |---|---|---|
 | Lifetime | Per trigger (seconds-minutes) | Long-lived |
 | Surface | Graph of agent CLI calls | A whole open-source application |
 | Billing | Per execution | Per minute, while running |
 | Best for | "When ticket lands, classify it" | "Host Grafana for the team" |
 
-Pick by how long the thing needs to run — see [Apps overview](./apps/) for the decision tree.
+An **Agent** is a deployed automation. An **App** is a hosted open-source application. Pick by how long the thing needs to run — see [Apps overview](./apps/) for the decision tree.
 
 ## How it compares
 

package/docs/legacy/test-automation.md

@@ -63,7 +63,7 @@ npx playwright test tests/login.spec.js
 
 ## Customizing Your Setup (Optional)
 
-If you want to customize the workflow, config, or nodes:
+If you want to customize the agent, config, or nodes:
 
 ```bash
 zibby init --agent cursor
@@ -82,7 +82,7 @@ This scaffolds:
 └── result-handler.js      # Post-execution hooks
 ```
 
-Without `zibby init`, the CLI uses the built-in default workflow automatically.
+Without `zibby init`, the CLI uses the built-in default agent automatically.
 
 ## Environment Variables
 

package/docs/packages/cli.md

@@ -16,18 +16,18 @@ zibby --version
 
 ## What it does
 
-- **Scaffolds** workflows: `zibby workflow new <name>`
-- **Runs** workflows locally (one-shot): `zibby workflow run <name>`
-- **Deploys** to Zibby Cloud (Heroku-style bundles): `zibby workflow deploy <name>`
-- **Triggers** deployed workflows: `zibby workflow trigger <uuid>`
-- **Tails** logs: `zibby workflow logs <uuid> -t`
+- **Scaffolds** agents: `zibby agent new <name>`
+- **Runs** agents locally (one-shot): `zibby agent run <name>`
+- **Deploys** to Zibby Cloud (Heroku-style bundles): `zibby agent deploy <name>`
+- **Triggers** deployed agents: `zibby agent trigger <uuid>`
+- **Tails** logs: `zibby agent logs <uuid> -t`
 - **Manages** auth: `zibby login`, `zibby logout`, `zibby status`
 
 The full command catalog lives at [CLI Reference](../cli-reference).
 
-## Self-contained workflow projects
+## Self-contained agent projects
 
-`zibby workflow new` creates a workflow as a **self-contained npm project** — its own `package.json`, its own `node_modules`. So a workflow can pull in arbitrary deps (PDF libraries, custom MCP servers, your own SDK) without polluting the parent project.
+`zibby agent new` creates an agent as a **self-contained npm project** — its own `package.json`, its own `node_modules`. So an agent can pull in arbitrary deps (PDF libraries, custom MCP servers, your own SDK) without polluting the parent project.
 
 ```
 my-app/
@@ -35,14 +35,14 @@ my-app/
 ├── src/
 └── .zibby/
     └── workflows/
-        └── my-pipeline/
-            ├── package.json     # workflow's own deps
+        └── my-agent/
+            ├── package.json     # agent's own deps
             ├── node_modules/
             ├── graph.mjs
             └── nodes/
 ```
 
-The cloud bundle build does the same — `npm install` runs *inside* the workflow folder, scoped to its own package.json.
+The cloud bundle build does the same — `npm install` runs *inside* the agent folder, scoped to its own package.json.
 
 ## Configuration
 
@@ -65,7 +65,7 @@ export default {
 };
 ```
 
-`zibby workflow deploy` resolves this file locally and ships the result as `zibby.config.json` inside the deploy bundle, so the cloud runtime sees the same `agent` block, per-node `models`, and other declarative knobs as your local runs. Function values are dropped at deploy time (config is data, not code) — if you need runtime variation in cloud, use [per-workflow env vars](../cloud/env-vars).
+`zibby agent deploy` resolves this file locally and ships the result as `zibby.config.json` inside the deploy bundle, so the cloud runtime sees the same `agent` block, per-node `models`, and other declarative knobs as your local runs. Function values are dropped at deploy time (config is data, not code) — if you need runtime variation in cloud, use [per-agent env vars](../cloud/env-vars).
 
 ## Source
 

package/docs/packages/core.md

@@ -7,7 +7,7 @@ title: '@zibby/core'
 
 [![npm](https://img.shields.io/npm/v/@zibby/core.svg)](https://www.npmjs.com/package/@zibby/core)
 
-The batteries — five built-in agent strategies, the runtime, and a re-export of the `@zibby/agent-workflow` engine. This is what `zibby workflow new` scaffolds workflows against.
+The batteries — five built-in agent strategies, the runtime, and a re-export of the `@zibby/agent-workflow` engine. This is what `zibby agent new` scaffolds agents against.
 
 ```bash
 npm install @zibby/core
@@ -63,7 +63,7 @@ Functions used by the cloud executor and Studio integration — `ZibbyRuntime`,
 
 | Goal | Pick |
 |---|---|
-| Build a workflow with built-in agents (cursor/claude/codex/gemini/assistant) | `@zibby/core` |
+| Build an agent with built-in strategies (cursor/claude/codex/gemini/assistant) | `@zibby/core` |
 | Embed the engine in your own app with custom agents only | `@zibby/agent-workflow` |
 | Use the CLI | `@zibby/cli` (transitively pulls both) |
 

package/docs/packages/mcp-cli.md

@@ -22,17 +22,17 @@ A Model Context Protocol (MCP) server that exposes the Zibby CLI surface — dep
 | `zibby_logout` | Clears the saved session. |
 | `zibby_status` | Who is logged in, how many projects are cached, whether the session is still valid. |
 | `zibby_list_projects` | List the Zibby projects the user has access to. |
-| `zibby_list_templates` | List official workflow templates (browser-test-automation, code-analysis, generate-test-cases, …). |
-| `zibby_scaffold_workflow` | Scaffold `.zibby/workflows/<name>/` from an official template. |
-| `zibby_validate_workflow` | Static-check a local workflow (~30 ms, no API call). |
-| `zibby_list_workflows` | List workflows: local, remote, or both. |
-| `zibby_deploy_workflow` | Deploy a local workflow to a project. |
-| `zibby_trigger_workflow` | Trigger a deployed workflow by UUID. Returns `jobId`. |
-| `zibby_workflow_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
-| `zibby_run_workflow_local` | Run a workflow on the user's machine one-shot, for debugging. No cloud. |
-| `zibby_download_workflow` | Pull a deployed workflow back to local. Requires explicit `confirm: true` from the agent. |
-
-**Destructive operations are intentionally not exposed.** Workflow deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.
+| `zibby_list_templates` | List official agent templates (browser-test-automation, code-analysis, generate-test-cases, …). |
+| `zibby_scaffold_agent` | Scaffold `.zibby/workflows/<name>/` from an official template. |
+| `zibby_validate_agent` | Static-check a local agent (~30 ms, no API call). |
+| `zibby_list_agents` | List agents: local, remote, or both. |
+| `zibby_deploy_agent` | Deploy a local agent to a project. |
+| `zibby_trigger_agent` | Trigger a deployed agent by UUID. Returns `jobId`. |
+| `zibby_agent_logs` | Fetch the latest N log lines from a run (one-shot — call again for newer lines). |
+| `zibby_run_agent_local` | Run an agent on the user's machine one-shot, for debugging. No cloud. |
+| `zibby_download_agent` | Pull a deployed agent back to local. Requires explicit `confirm: true` from the agent. |
+
+**Destructive operations are intentionally not exposed.** Agent deletion, env-var mutation, schedule changes, and credential management stay in the `zibby` CLI directly. The agent has to involve the user out-of-band for those.
 
 ## Install
 
@@ -128,14 +128,14 @@ If your agent on Windows can't find `npx`, wrap with `cmd /c`:
 ```
 User:  Deploy the browser-test template to my "playhouse" project.
 Agent: → zibby_list_projects
-       → zibby_scaffold_workflow (browser-test-automation → .zibby/workflows/playhouse-tests/)
-       → zibby_validate_workflow
-       → zibby_deploy_workflow
+       → zibby_scaffold_agent (browser-test-automation → .zibby/workflows/playhouse-tests/)
+       → zibby_validate_agent
+       → zibby_deploy_agent
        → "Deployed v1 of playhouse-tests. UUID 988…"
 
 User:  Run it against staging.zibby.dev.
-Agent: → zibby_trigger_workflow (input: { url: "https://staging.zibby.dev" })
-       → zibby_workflow_logs (lines: 200, jobId: "abc-123")
+Agent: → zibby_trigger_agent (input: { url: "https://staging.zibby.dev" })
+       → zibby_agent_logs (lines: 200, jobId: "abc-123")
        → "Run completed. Found 0 errors."
 ```
 
@@ -144,7 +144,7 @@ Agent: → zibby_trigger_workflow (input: { url: "https://staging.zibby.dev" })
 Two-stage by design (mirrors how the `zibby` CLI works):
 
 1. **Session token** (`zibby_login`) — device-code OAuth via browser. Identifies the user.
-2. **Per-project API tokens** — fetched at login time and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_workflow`.
+2. **Per-project API tokens** — fetched at login time and cached locally. The MCP server picks the right token automatically when you call a project-scoped tool like `zibby_deploy_agent`.
 
 All credentials live in `~/.zibby/config.json` (mode `0600`). The same file `zibby login` writes — so if you've already done `zibby login` from a terminal, the MCP server picks up that session.
 
@@ -156,7 +156,7 @@ The user's password never touches the MCP server: login is OAuth in the browser,
 - **Minimum env passthrough** — only `HOME`, `USER`, `PATH`, and the project-scoped `ZIBBY_API_KEY` reach the child CLI process.
 - **API tokens never returned to the agent** — they live in `~/.zibby/config.json` only, read server-side per call.
 - **Destructive ops excluded** — see the table above.
-- **`zibby_download_workflow` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.
+- **`zibby_download_agent` requires `confirm: true`** — the schema rejects calls without it. Agents must explicitly opt in after confirming the destination path with the user.
 
 ## Troubleshooting