@zibby/skills 0.1.33 → 0.1.35

package/docs/cloning-repositories.md

@@ -3,13 +3,13 @@ sidebar_position: 8
 title: Cloning Repositories
 ---
 
-# Cloning Repositories in Custom Workflows
+# Cloning Repositories in Custom Agents
 
-Custom workflows can clone your project's configured repositories (GitHub/GitLab) using the `cloneRepo()` helper function from `@zibby/core`.
+Custom agents can clone your project's configured repositories (GitHub/GitLab) using the `cloneRepo()` helper function from `@zibby/core`.
 
 ## Overview
 
-When your workflow runs in the cloud, it has access to:
+When your agent runs in the cloud, it has access to:
 - All repositories configured in your project settings (GitHub/GitLab)
 - Authenticated tokens for cloning (injected securely by the platform)
 - A clean isolated container environment
@@ -135,9 +135,9 @@ If a repository fails to clone, its value will be `null`:
 }
 ```
 
-## Complete Example Workflow
+## Complete Example Agent
 
-Here's a full workflow that clones repos and runs analysis:
+Here's a full agent that clones repos and runs analysis:
 
 ```javascript
 // graph.mjs
@@ -224,11 +224,11 @@ Return a comprehensive security audit report.`;
 ## How It Works
 
 1. **Project Configuration**: You configure repositories in your project settings (Web UI)
-2. **Secure Token Injection**: When the workflow runs, Zibby injects:
+2. **Secure Token Injection**: When the agent runs, Zibby injects:
    - `REPOS` env var (array of repo metadata with clone URLs)
    - `GITHUB_TOKEN` and/or `GITLAB_TOKEN` (OAuth tokens for authentication)
 3. **Authenticated Clone**: `cloneRepo()` constructs authenticated URLs and clones via `git clone`
-4. **Isolation**: Each workflow run gets a fresh container with no cached state
+4. **Isolation**: Each agent run gets a fresh container with no cached state
 
 ## Supported Platforms
 
@@ -269,7 +269,7 @@ Common failure reasons:
 
 ## Local Development
 
-When running workflows locally (`zibby workflow run`), you'll need to:
+When running agents locally (`zibby agent run`), you'll need to:
 1. Set `REPOS` env var manually (JSON array)
 2. Provide `GITHUB_TOKEN` or `GITLAB_TOKEN`
 3. Ensure `git` is installed
@@ -279,7 +279,7 @@ Example for local testing:
 ```bash
 export REPOS='[{"name":"myorg/backend","provider":"github","cloneUrl":"https://github.com/myorg/backend.git"}]'
 export GITHUB_TOKEN="ghp_your_token"
-zibby workflow run my-workflow
+zibby agent run my-agent
 ```
 
 In production (cloud), these are injected automatically.

package/docs/cloud/bundles.md

@@ -5,12 +5,12 @@ title: Bundle build (Heroku-style)
 
 # Bundle build
 
-When you `zibby workflow deploy`, two things happen:
+When you `zibby agent deploy`, two things happen:
 
-1. **Source upload** — your workflow folder (sources only, no `node_modules`) is sent to S3 via a presigned PUT URL. The CLI does this; the backend never has S3 IAM credentials for your account's bucket.
+1. **Source upload** — your agent folder (sources only, no `node_modules`) is sent to S3 via a presigned PUT URL. The CLI does this; the backend never has S3 IAM credentials for your account's bucket.
 2. **Bundle build** — a CodeBuild job downloads the sources, runs `npm install --omit=dev`, packages a tarball, uploads it back to S3.
 
-The tarball is what the cloud runtime downloads at trigger time. **No `npm install` happens at runtime** — workflows boot in seconds regardless of dependency tree size.
+The tarball is what the cloud runtime downloads at trigger time. **No `npm install` happens at runtime** — agents boot in seconds regardless of dependency tree size.
 
 ## What's in the bundle
 
@@ -41,7 +41,7 @@ export default {
 
 ## Why this matters
 
-Without bundling, every cloud trigger would run `npm install` inside the ECS task. For a typical workflow with `@zibby/core` + a few skills, that's 30–90 seconds per cold start. With the bundle:
+Without bundling, every cloud trigger would run `npm install` inside the ECS task. For a typical agent with `@zibby/core` + a few skills, that's 30–90 seconds per cold start. With the bundle:
 
 ```
 trigger → tarball download (3s) → graph.run() → done
@@ -64,23 +64,23 @@ Pass `--verbose` (or set `ZIBBY_DEPLOY_VERBOSE=1`) to see the raw CodeBuild logs
 
 ## Re-deploys reuse the bundle path
 
-The bundle URL is keyed by workflow UUID — re-deploys overwrite the previous bundle. Old executions in flight finish against the *previous* bundle (no rug-pull) because each ECS task downloads the tarball at the moment it starts.
+The bundle URL is keyed by agent UUID — re-deploys overwrite the previous bundle. Old executions in flight finish against the *previous* bundle (no rug-pull) because each ECS task downloads the tarball at the moment it starts.
 
 ## Security model
 
 The CodeBuild role has **zero S3 IAM permissions**. It receives presigned GET (for sources) and PUT (for bundle) URLs as build-time env vars. URLs are scoped to single keys, expire after 15 minutes.
 
-This means a malicious `postinstall` script in a workflow's `package.json` can't escape its sandbox to read other customers' bundles or sources.
+This means a malicious `postinstall` script in an agent's `package.json` can't escape its sandbox to read other customers' bundles or sources.
 
 ## Bundle size
 
 Typical: 100–200 MB compressed. Mostly node_modules. The bundle includes everything `npm install --omit=dev` produces — runtime deps only, no dev deps.
 
-To slim it: audit your workflow's `package.json` for unused deps, and prefer the lightest agent SDK that does the job.
+To slim it: audit your agent's `package.json` for unused deps, and prefer the lightest agent SDK that does the job.
 
 ## Source-fetch fallback
 
-If the bundle is missing or fails to extract, the cloud runtime falls back to source-fetch + runtime `npm install`. Slower, but workflows still run. You'll see this in logs:
+If the bundle is missing or fails to extract, the cloud runtime falls back to source-fetch + runtime `npm install`. Slower, but agents still run. You'll see this in logs:
 
 ```
 [setup] Bundle extract failed (...); falling back to source install

package/docs/cloud/dedicated-egress.md

@@ -5,12 +5,12 @@ title: Dedicated egress IP
 
 # Dedicated egress IP
 
-By default, every Zibby workflow exits via a random AWS IP that changes every run.
-For most customers that's fine — but if your workflow needs to talk to a service
+By default, every Zibby agent exits via a random AWS IP that changes every run.
+For most customers that's fine — but if your agent needs to talk to a service
 behind a firewall (private GitLab, Salesforce, Oracle Cloud, internal API behind a
 corporate VPN), the random-IP behavior makes it unusable.
 
-The **dedicated egress IP** addon pins all your workflow's outbound traffic to a
+The **dedicated egress IP** addon pins all your agent's outbound traffic to a
 single static IP that you can whitelist once on the destination service.
 
 ## Pricing
@@ -34,11 +34,11 @@ single static IP that you can whitelist once on the destination service.
    Internet (sees your static IP, e.g. 54.66.241.180)
 ```
 
-Every outbound HTTPS call from your workflow exits via your dedicated IP:
+Every outbound HTTPS call from your agent exits via your dedicated IP:
 
 | What | Whether it tunnels |
 |---|---|
-| `fetch()` from workflow code | ✅ via static IP |
+| `fetch()` from agent code | ✅ via static IP |
 | `git clone` private repos | ✅ via static IP |
 | `npm install` from private registries | ✅ via static IP |
 | `curl` / `wget` in shell scripts | ✅ via static IP |
@@ -110,7 +110,7 @@ Your IP is **stable for as long as you have the addon enabled**:
 
 - Survives Zibby infrastructure changes (we replace proxy boxes regularly)
 - Survives our region failovers
-- Survives your own workflow redeploys
+- Survives your own agent redeploys
 
 The only way the IP changes is if **you** disable the addon, in which case the IP
 is released back to AWS at the end of your billing period.

package/docs/cloud/env-vars.md

@@ -1,26 +1,26 @@
 ---
 sidebar_position: 4
-title: Per-workflow env vars
+title: Per-agent env vars
 ---
 
-# Per-workflow env vars
+# Per-agent env vars
 
-Each deployed workflow has its own encrypted env-var bag. The cloud runtime injects those vars into the Fargate task that runs the workflow — they show up in `process.env` like any other env var.
+Each deployed agent has its own encrypted env-var bag. The cloud runtime injects those vars into the Fargate task that runs the agent — they show up in `process.env` like any other env var.
 
-Use this for credentials that are **specific to one workflow** — different `ANTHROPIC_API_KEY` per pipeline, a workflow-only `DATABASE_URL`, an external webhook secret. Project-wide secrets stay on the project record (set in dashboard); workflow env wins on conflict.
+Use this for credentials that are **specific to one agent** — different `ANTHROPIC_API_KEY` per agent, an agent-only `DATABASE_URL`, an external webhook secret. Project-wide secrets stay on the project record (set in dashboard); agent env wins on conflict.
 
 ## The fast path: `--env` at deploy
 
-Most users want to ship a `.env` alongside the workflow:
+Most users want to ship a `.env` alongside the agent:
 
 ```bash
-zibby workflow deploy my-pipeline --env .env
+zibby agent deploy my-agent --env .env
 ```
 
-The CLI deploys the workflow as usual, then syncs the `.env` into per-workflow env vars. You'll see:
+The CLI deploys the agent as usual, then syncs the `.env` into per-agent env vars. You'll see:
 
 ```
-✔ Deployed my-pipeline (v1)
+✔ Deployed my-agent (v1)
 ✔ Bundle ready (78s)
 ✔ Synced 4 env vars from .env
 ```
@@ -28,21 +28,21 @@ The CLI deploys the workflow as usual, then syncs the `.env` into per-workflow e
 Multiple files merge with later wins (mirrors how dotenv libraries usually layer):
 
 ```bash
-zibby workflow deploy my-pipeline --env .env --env .env.prod
+zibby agent deploy my-agent --env .env --env .env.prod
 ```
 
-## Manage after deploy: `zibby workflow env`
+## Manage after deploy: `zibby agent env`
 
-Four verbs, all keyed by the workflow UUID (from `zibby workflow list` or `.zibby-deploy.json`):
+Four verbs, all keyed by the agent UUID (from `zibby agent list` or `.zibby-deploy.json`):
 
 ```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
+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
 ```
 
-`set` is for surgical updates — leaves every other key alone. `push` is the deploy-flow `--env` exposed as a standalone command for when you want to update env without redeploying the workflow itself.
+`set` is for surgical updates — leaves every other key alone. `push` is the deploy-flow `--env` exposed as a standalone command for when you want to update env without redeploying the agent itself.
 
 `list` only returns key names, never values. Once you set a value, the only place it surfaces is inside the running container.
 
@@ -50,19 +50,19 @@ zibby workflow env push <uuid> --file .env [--file .env.prod]  # bulk replace
 
 Rotate one key:
 ```bash
-zibby workflow env set 1a255ded-9f57-44ad-81cf-70726b13d653 ANTHROPIC_API_KEY=sk-ant-rotated
+zibby agent env set 1a255ded-9f57-44ad-81cf-70726b13d653 ANTHROPIC_API_KEY=sk-ant-rotated
 ```
 
-Wipe all env on a workflow (push an empty file):
+Wipe all env on an agent (push an empty file):
 ```bash
-zibby workflow env push <uuid> --file /dev/null
+zibby agent env push <uuid> --file /dev/null
 ```
 
 CI rotation (GitHub Actions):
 ```yaml
 - run: |
     echo "ANTHROPIC_API_KEY=$ANTHROPIC_KEY" > .env.cd
-    npx @zibby/cli workflow env push $WORKFLOW_UUID --file .env.cd
+    npx @zibby/cli agent env push $WORKFLOW_UUID --file .env.cd
   env:
     ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
     WORKFLOW_UUID: ${{ vars.WORKFLOW_UUID }}
@@ -74,10 +74,10 @@ CI rotation (GitHub Actions):
 When a Fargate task starts, env vars come from three layers (later wins):
 
 ```
-built-in container vars  →  project secrets (DDB)  →  workflow env (DDB)
+built-in container vars  →  project secrets (DDB)  →  agent env (DDB)
 ```
 
-So if both your project record and your workflow env define `ANTHROPIC_API_KEY`, the workflow's value is what `process.env.ANTHROPIC_API_KEY` returns inside the run.
+So if both your project record and your agent env define `ANTHROPIC_API_KEY`, the agent's value is what `process.env.ANTHROPIC_API_KEY` returns inside the run.
 
 ## Validation
 
@@ -87,11 +87,11 @@ So if both your project record and your workflow env define `ANTHROPIC_API_KEY`,
 | Value | Any string. Empty string is allowed. |
 | `.env` files | Standard dotenv syntax — comments, quoted values, blank lines, `KEY=value` per line. |
 
-The CLI validates locally before the API round-trip, so `zibby workflow env set <uuid> lowercase=v` fails fast with a readable message instead of a 400.
+The CLI validates locally before the API round-trip, so `zibby agent env set <uuid> lowercase=v` fails fast with a readable message instead of a 400.
 
-## Use case: multi-agent workflows
+## Use case: multi-vendor agents
 
-Different nodes in the same workflow may want to call different model vendors:
+Different nodes in the same agent may want to call different model vendors:
 
 ```js
 // graph.mjs
@@ -110,7 +110,7 @@ CURSOR_API_KEY=key_...
 OPENAI_API_KEY=sk-...
 EOF
 
-zibby workflow deploy multi-agent --env .env
+zibby agent deploy multi-agent --env .env
 ```
 
 Each agent reads its own env var when invoked. No prompt-stuffing keys, no per-node config.
@@ -118,13 +118,13 @@ Each agent reads its own env var when invoked. No prompt-stuffing keys, no per-n
 ## Security model
 
 - **Encryption**: KMS envelope encryption with per-account keys. The plaintext never lands in CloudWatch, DDB, or Lambda logs.
-- **Access control**: every env command needs project-level access on the workflow's project — checked on every request.
+- **Access control**: every env command needs project-level access on the agent's project — checked on every request.
 - **Audit**: KMS logs every decrypt operation. Cross-reference with `WORKFLOW_JOB_ID` to see exactly which run pulled which secret.
-- **Rotation**: `zibby workflow env set` with a new value — the next triggered run picks it up. Currently in-flight runs keep using the value they decrypted at start time.
+- **Rotation**: `zibby agent env set` with a new value — the next triggered run picks it up. Currently in-flight runs keep using the value they decrypted at start time.
 
 ## What this is *not*
 
-- **Not for the project's primary credentials** — those live on the project record (dashboard → Project → Secrets). Use workflow env for *workflow-specific* overrides.
+- **Not for the project's primary credentials** — those live on the project record (dashboard → Project → Secrets). Use agent env for *agent-specific* overrides.
 - **Not a values-readable store** — `list` returns key names only. If you need to retrieve the value, you'll have to push it again. This is intentional.
 - **Not 1Password / Vault** — no rotation policies, no version history. Plain CRUD.
 

package/docs/cloud/limits.md

@@ -5,24 +5,24 @@ title: Limits & quotas
 
 # Limits & quotas
 
-## Workflow runtime cap
+## Agent runtime cap
 
-Every workflow execution has a **30-minute hard cap**. If a workflow exceeds it, the
+Every agent execution has a **30-minute hard cap**. If an agent exceeds it, the
 container is terminated with exit code `124` (timeout) and the execution is marked
 `failed` with reason `TIMEOUT`.
 
 Why this exists:
-- Stops runaway workflows (infinite loops, hung HTTP calls, stuck npm installs)
+- Stops runaway agents (infinite loops, hung HTTP calls, stuck npm installs)
   from burning unbounded compute
 - Predictable per-execution cost ceiling
 - Industry standard — GitHub Actions defaults to 6 hours, GitLab CI defaults to
   1 hour, Vercel functions cap at 5 minutes. We picked 30 min as the sweet spot
-  for AI-driven workflows
+  for AI-driven agents
 
-If your workflow needs to run longer:
+If your agent needs to run longer:
 - Split it into multiple shorter executions chained via input/output
 - Move long-running work (large npm installs, video processing) into your bundled
-  artifact at deploy time so the workflow itself stays short
+  artifact at deploy time so the agent itself stays short
 - Contact us about a Pro tier with a longer cap
 
 The cap is enforced **inside** the container by a watchdog timer set on startup,
@@ -43,7 +43,7 @@ marked failed.
 
 ## Container freedom (what you CAN do)
 
-Inside your container, your workflow has **full control**:
+Inside your container, your agent has **full control**:
 
 - Install any npm package (`npm install`, `pip install`, `apt install` if root)
 - Run any shell command (`curl`, `git`, `docker`-in-docker not supported)
@@ -58,7 +58,7 @@ no side effects on Zibby infrastructure.
 
 | Boundary | Why |
 |---|---|
-| Talk to other customers' workflows | Each task is a separate isolated container |
+| Talk to other customers' agents | Each task is a separate isolated container |
 | Use someone else's static IP | Only your account's IP is reachable from your task |
 | Run beyond the 30-min cap | Watchdog kills the process |
 | Read Zibby infra secrets | Container IAM role only sees your execution data |
@@ -66,7 +66,7 @@ no side effects on Zibby infrastructure.
 
 ## Outbound network
 
-By default your workflow exits via a random AWS IP that changes every run. If you
+By default your agent exits via a random AWS IP that changes every run. If you
 need a stable IP for whitelisting customer firewalls, see
 [Dedicated egress IP](./dedicated-egress) ($50/mo addon).
 
@@ -74,8 +74,8 @@ need a stable IP for whitelisting customer firewalls, see
 
 | Endpoint | Limit |
 |---|---|
-| Trigger workflow | 60/min per account |
+| Trigger agent | 60/min per account |
 | Read logs | 600/min per account |
-| Deploy workflow | 30/hour per account |
+| Deploy agent | 30/hour per account |
 
 Hitting a rate limit returns `429 Too Many Requests` with a `Retry-After` header.

package/docs/cloud/triggering.md

@@ -5,18 +5,18 @@ title: Triggering programmatically
 
 # Triggering programmatically
 
-The CLI is the public surface for triggering workflows. CI runners, cron hosts, webhook handlers — all of them shell out to the same command:
+The CLI is the public surface for triggering agents. CI runners, cron hosts, webhook handlers — all of them shell out to the same command:
 
 ```bash
-zibby workflow trigger <uuid>
-zibby workflow trigger <uuid> -p ticket=BUG-123
-zibby workflow trigger <uuid> --input '{"ticket":"BUG-123","priority":"high"}'
-zibby workflow trigger <uuid> --input-file payload.json
+zibby agent trigger <uuid>
+zibby agent trigger <uuid> -p ticket=BUG-123
+zibby agent trigger <uuid> --input '{"ticket":"BUG-123","priority":"high"}'
+zibby agent trigger <uuid> --input-file payload.json
 ```
 
 Auth: set `ZIBBY_API_KEY` in the environment, or run `zibby login` once on a workstation. Either works; the CLI picks up whichever is available.
 
-The flag surface is identical to `zibby workflow run` (local) — same `-p / --input / --input-file`, plus `--idempotency-key` for the cloud-only dedup case below. Flip the verb and the same call shape goes from local to remote.
+The flag surface is identical to `zibby agent run` (local) — same `-p / --input / --input-file`, plus `--idempotency-key` for the cloud-only dedup case below. Flip the verb and the same call shape goes from local to remote.
 
 ### Input precedence
 
@@ -29,7 +29,7 @@ When more than one input source is provided, they merge with this **precedence (
 This means the common pattern of "load a base payload from disk, override a few keys for this run" works without manual merging:
 
 ```bash
-zibby workflow trigger <uuid> --input-file payload.json -p priority=urgent
+zibby agent trigger <uuid> --input-file payload.json -p priority=urgent
 ```
 
 ## CI / cron
@@ -39,10 +39,10 @@ Anywhere you can shell out, call the CLI. Don't hand-roll an HTTP client — you
 ### GitHub Actions
 
 ```yaml
-- name: Trigger Zibby workflow
+- name: Trigger Zibby agent
   run: |
     npm i -g @zibby/cli
-    zibby workflow trigger $WORKFLOW_UUID -p sha=$GITHUB_SHA -p pr=$PR_NUMBER
+    zibby agent trigger $WORKFLOW_UUID -p sha=$GITHUB_SHA -p pr=$PR_NUMBER
   env:
     WORKFLOW_UUID: 2b1ea07f-3ede-4bfd-a51d-431f0bab008e
     ZIBBY_API_KEY: ${{ secrets.ZIBBY_API_KEY }}
@@ -61,7 +61,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - run: npm i -g @zibby/cli
-      - run: zibby workflow trigger $UUID --input '{"weekly":true}'
+      - run: zibby agent trigger $UUID --input '{"weekly":true}'
         env:
           UUID: ${{ vars.WORKFLOW_UUID }}
           ZIBBY_API_KEY: ${{ secrets.ZIBBY_API_KEY }}
@@ -79,7 +79,7 @@ app.post('/webhook', (req, res) => {
 
   try {
     execFileSync('zibby', [
-      'workflow', 'trigger', process.env.WORKFLOW_UUID,
+      'agent', 'trigger', process.env.WORKFLOW_UUID,
       '--input', JSON.stringify(req.body),
       '--idempotency-key', req.headers['x-event-id'],
     ], { env: process.env, stdio: 'pipe' });
@@ -97,7 +97,7 @@ If your runtime can't spawn a Node CLI (constrained Lambda layers, edge runtimes
 Pass an idempotency key to deduplicate triggers within a 24-hour window:
 
 ```bash
-zibby workflow trigger <uuid> \
+zibby agent trigger <uuid> \
   -p ticket=BUG-123 \
   --idempotency-key webhook-2026-05-02-event-7
 ```
@@ -109,14 +109,14 @@ Same key + same input within 24h returns the original `jobId` instead of startin
 After triggering, the CLI prints the `jobId`. To watch the execution:
 
 ```bash
-zibby workflow logs <uuid> -t
+zibby agent logs <uuid> -t
 ```
 
-See [`workflow logs` in the CLI Reference](../cli-reference#workflow-logs).
+See [`agent logs` in the CLI Reference](../cli-reference#agent-logs).
 
-## Per-workflow env vars
+## Per-agent env vars
 
-If your workflow needs credentials or config that's specific to it (different `ANTHROPIC_API_KEY` per pipeline, a workflow-only `DATABASE_URL`, etc.), set them via the env-var API — see [Per-workflow env vars](./env-vars). They get injected into the Fargate task at trigger time and override anything set on the project record.
+If your agent needs credentials or config that's specific to it (different `ANTHROPIC_API_KEY` per agent, an agent-only `DATABASE_URL`, etc.), set them via the env-var API — see [Per-agent env vars](./env-vars). They get injected into the Fargate task at trigger time and override anything set on the project record.
 
 ## Quotas
 

package/docs/concepts/agents.md

@@ -92,7 +92,7 @@ Then a node can use it:
 graph.addNode('plan', { prompt, outputSchema: Plan, agent: 'mine' });
 ```
 
-The framework ships **zero** agent strategies bundled — `@zibby/agent-workflow` is BYO. The five built-ins above live in `@zibby/core`, which is what `zibby workflow new` scaffolds and what the cloud runtime preloads.
+The framework ships **zero** agent strategies bundled — `@zibby/agent-workflow` is BYO. The five built-ins above live in `@zibby/core`, which is what `zibby agent new` scaffolds and what the cloud runtime preloads.
 
 ## Authentication
 
@@ -106,7 +106,7 @@ The framework ships **zero** agent strategies bundled — `@zibby/agent-workflow
 
 In Zibby Cloud, you have two options:
 
-- **Project-wide credentials**: set once on the project record (dashboard → Project → Secrets) — every workflow in the project uses them.
-- **Per-workflow overrides**: set on a single workflow via [`PUT /workflows/<uuid>/env`](../cloud/env-vars) — useful when one pipeline needs a different `ANTHROPIC_API_KEY` from the rest of the project, or when one workflow needs to talk to multiple agent vendors with their own keys.
+- **Project-wide credentials**: set once on the project record (dashboard → Project → Secrets) — every agent in the project uses them.
+- **Per-agent overrides**: set on a single agent via [`PUT /workflows/<uuid>/env`](../cloud/env-vars) — useful when one agent needs a different `ANTHROPIC_API_KEY` from the rest of the project, or when one agent needs to talk to multiple agent vendors with their own keys.
 
-Workflow env wins over project secrets on conflict (last-write-wins inside the Fargate task).
+Agent env wins over project secrets on conflict (last-write-wins inside the Fargate task).

package/docs/concepts/sessions.md

@@ -5,7 +5,7 @@ title: Sessions & artifacts
 
 # Sessions & artifacts
 
-Every workflow run — local or cloud — produces a **session folder** under `.zibby/output/sessions/<sessionId>/`. The folder is the canonical record of what happened.
+Every agent run — local or cloud — produces a **session folder** under `.zibby/output/sessions/<sessionId>/`. The folder is the canonical record of what happened.
 
 ## What's inside
 
@@ -31,7 +31,7 @@ Format: `<unix_ms>_<random>`. Generated when the graph starts running.
 You can override via:
 
 ```bash
-zibby workflow run my-pipeline --session 1777678254943_ymcw
+zibby agent run my-agent --session 1777678254943_ymcw
 ```
 
 Useful for replay — re-run from a saved input/state without re-paying earlier nodes.
@@ -39,7 +39,7 @@ Useful for replay — re-run from a saved input/state without re-paying earlier
 ## Replay a session
 
 ```bash
-zibby workflow run my-pipeline \
+zibby agent run my-agent \
   --session 1777678254943_ymcw \
   --node verify   # only re-run the 'verify' node
 ```
@@ -48,19 +48,19 @@ The graph reads `state.plan` and `state.implement` from the saved session and on
 
 ## Cloud sessions
 
-Cloud runs land in the same `.zibby/output/sessions/` layout, just inside the ECS container's `/workspace/`. The session folder is uploaded to S3 at the end of each run; `zibby workflow logs <uuid> -t` streams CloudWatch logs in real time.
+Cloud runs land in the same `.zibby/output/sessions/` layout, just inside the ECS container's `/workspace/`. The session folder is uploaded to S3 at the end of each run; `zibby agent logs <uuid> -t` streams CloudWatch logs in real time.
 
 To download a finished cloud session locally:
 
 ```bash
-zibby workflow download <uuid>
+zibby agent download <uuid>
 ```
 
-This pulls the workflow source (so you can edit and redeploy) plus the most recent execution's session folder.
+This pulls the agent source (so you can edit and redeploy) plus the most recent execution's session folder.
 
 ## Studio integration
 
-[Zibby Studio](https://zibby.app) is a desktop UI that watches `.zibby/output/sessions/`. Anything that writes a session folder shows up in Studio automatically — pin a session, watch state evolve live, or stop a workflow from the Stop button.
+[Zibby Studio](https://zibby.app) is a desktop UI that watches `.zibby/output/sessions/`. Anything that writes a session folder shows up in Studio automatically — pin a session, watch state evolve live, or stop an agent from the Stop button.
 
 The protocol is documented and stable:
 

package/docs/concepts/state.md

@@ -5,7 +5,7 @@ title: State & schema
 
 # State & schema
 
-Every workflow run carries one **state** object that flows from node to node. State is the only handoff mechanism — there's no shared globals, no hidden context.
+Every agent run carries one **state** object that flows from node to node. State is the only handoff mechanism — there's no shared globals, no hidden context.
 
 ## Shape
 

package/docs/concepts/sub-graphs.md

@@ -5,13 +5,13 @@ title: Sub-graphs (parent → child)
 
 # Sub-graphs
 
-A **sub-graph node** runs another deployed workflow as a child of the current one. Use it when a step is large enough to deserve its own workflow definition — its own state schema, its own version, its own activity-tab history — but you want a parent to dispatch it as part of a larger flow.
+A **sub-graph node** runs another deployed agent as a child of the current one. Use it when a step is large enough to deserve its own workflow definition — its own state schema, its own version, its own activity-tab history — but you want a parent to dispatch it as part of a larger flow.
 
 The shape is one extra field on the existing node config:
 
 ```js
 g.addNode('audit', {
-  workflow: 'deep-audit',   // ← name of another workflow in this project
+  workflow: 'deep-audit',   // ← name of another agent in this project
 });
 ```
 
@@ -22,7 +22,7 @@ That's it. No new imports, no UUID, no separate class. The engine recognizes `wo
 | Scenario | Sub-graph? |
 |---|---|
 | Two parents need the same multi-node flow | ✅ Yes — define it once as a child, reference by name |
-| One step needs different state schema than the rest | ✅ Yes — each workflow has its own schema |
+| One step needs different state schema than the rest | ✅ Yes — each agent has its own schema |
 | You want per-step activity-tab history + replay | ✅ Yes — each child run gets its own row |
 | Step is a single LLM call | ❌ No — just add a regular node |
 | Step has its own retry policy | Either works, but a sub-graph gives independent control |
@@ -77,7 +77,7 @@ g.addNode('audit', {
 
 ## How state flows
 
-Each workflow has its own state schema — they're independent. The parent must transform its state into the child's input shape, and (optionally) extract whatever it needs back out.
+Each agent has its own state schema — they're independent. The parent must transform its state into the child's input shape, and (optionally) extract whatever it needs back out.
 
 ### A complete example — `parent-orchestrator` calls `child-doubler`
 
@@ -184,13 +184,13 @@ err.subgraphStatus     // 'failed' | 'canceled' | 'timeout'
 
 ## What's deployed vs what you write
 
-You only ever reference workflows by **name**. The cloud handles the UUID resolution.
+You only ever reference agents by **name**. The cloud handles the UUID resolution.
 
 | Stage | What you write | What the backend does |
 |---|---|---|
-| `zibby workflow deploy child-doubler` | nothing about UUIDs | mints UUID, stores `(projectId, workflowType='child-doubler', uuid='…')` |
+| `zibby agent deploy child-doubler` | nothing about UUIDs | mints UUID, stores `(projectId, workflowType='child-doubler', uuid='…')` |
 | `subgraph('child-doubler')` in parent code | just the name | stored as a string in the parent's graph definition |
-| `zibby workflow deploy parent-orchestrator` | nothing | looks up `'child-doubler'` → UUID, snapshots the dependency |
+| `zibby agent deploy parent-orchestrator` | nothing | looks up `'child-doubler'` → UUID, snapshots the dependency |
 | Parent runs in Fargate → hits sub-graph node | nothing | POSTs to `/workflows/<uuid>/trigger` with `parentExecutionId` |
 
 Names are unique per project (DDB primary key enforces this), so `subgraph('child-doubler')` resolves unambiguously within the parent's project.
@@ -208,14 +208,14 @@ Each child execution row carries `parentExecutionId` pointing at the parent. The
 
 Sub-graph dispatch needs the `PROGRESS_API_URL` env var (the public API base). That's set automatically on Fargate runs. For local dev, you have two options:
 
-1. **Deploy both workflows to cloud, then trigger the parent.** The cloud path always works.
+1. **Deploy both agents to cloud, then trigger the parent.** The cloud path always works.
 2. **Mock the trigger + status endpoints locally.** See [`workflows/parent-orchestrator/mock-server.mjs`](https://github.com/ZibbyHQ/agent-workflow/tree/main/examples) in the agent-workflow repo for a 90-line example that simulates the dispatch + poll loop.
 
 In-process sub-graph execution (running the child in the parent's Node process directly, no HTTP) is **not supported** — we picked consistency between local and cloud over the 10s spawn-time savings.
 
 ## Cross-project sub-graphs
 
-`workflow: 'name'` resolves within the parent's own project. To call another project's workflow, pass an explicit project ID:
+`workflow: 'name'` resolves within the parent's own project. To call another project's agent, pass an explicit project ID:
 
 ```js
 g.addNode('audit', {