@zibby/skills 0.1.11 → 0.1.12

package/docs/cloud/dedicated-egress.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 5
+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
+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
+single static IP that you can whitelist once on the destination service.
+
+## Pricing
+
+**$50/month per account.** All your projects share the same IP.
+
+## How it works
+
+```
+   Your Fargate task (random IP per run)
+        │
+        │  All HTTPS traffic tunneled through:
+        ▼
+   ┌──────────────────────────────────┐
+   │  Zibby's egress proxy            │
+   │   - Validates your auth          │
+   │   - Routes via YOUR static IP    │
+   └──────────────────────────────────┘
+        │
+        ▼
+   Internet (sees your static IP, e.g. 54.66.241.180)
+```
+
+Every outbound HTTPS call from your workflow exits via your dedicated IP:
+
+| What | Whether it tunnels |
+|---|---|
+| `fetch()` from workflow 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 |
+| AWS SDK calls (S3, DynamoDB) | ❌ direct (AWS doesn't care about source IP) |
+
+## Enabling
+
+```bash
+# 1. Enable the addon for your account (paid)
+zibby deploy --dedicated-ip enable
+
+# Output:
+#   Provisioning your dedicated egress IP...
+#   Done in 8s.
+#
+#   Your static IP: 54.66.241.180
+#
+#   Add this to your firewall allowlist, then opt projects in:
+#     zibby deploy --dedicated-ip use --project <project-id>
+
+# 2. Opt each project in (free)
+zibby deploy --dedicated-ip use --project my-project
+```
+
+## Checking status
+
+```bash
+zibby deploy --dedicated-ip status
+
+# Output:
+#   Dedicated egress IP: active
+#
+#   Your static IP:  54.66.241.180
+#   Provisioned:     2026-05-02
+#
+#   Projects opted in:
+#     ✓ my-project
+#     ✗ other-project (not opted in)
+```
+
+## Whitelisting on common services
+
+**GitLab self-hosted:**
+```
+Admin → Settings → Network → Outbound requests
+→ Allowlist: 54.66.241.180
+```
+
+**GitHub Enterprise:**
+```
+Site admin → Authentication → IP allowlist
+→ Add: 54.66.241.180
+```
+
+**AWS Security Group (e.g. for a private RDS/ECS endpoint):**
+```
+Inbound rule → HTTPS → Source: 54.66.241.180/32
+```
+
+**Salesforce:**
+```
+Setup → Network Access → Trusted IP ranges
+→ Add: 54.66.241.180 to 54.66.241.180
+```
+
+## What stays the same
+
+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
+
+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.
+
+## Disabling
+
+```bash
+zibby deploy --dedicated-ip disable
+```
+
+The IP stays attached until the end of your current billing period (no immediate
+proration). After that, the IP is released.
+
+If you re-enable later, you'll get a **different** IP — we can't guarantee the
+same one. Re-whitelist on your destination services if you re-enable.
+
+## Per-project IPs
+
+Currently every project on your account shares the same IP. If you need separate
+IPs per project (for compliance isolation, dev/staging/prod separation, etc.),
+contact support.
+
+## Limitations
+
+- Currently only available in `ap-southeast-2` (Sydney). Multi-region coming.
+- Only IPv4. No IPv6 yet.
+- Outbound only. We don't host inbound services on your IP.

package/docs/cloud/env-vars.md

@@ -0,0 +1,144 @@
+---
+sidebar_position: 4
+title: Per-workflow env vars
+---
+
+# Per-workflow 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.
+
+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.
+
+## The fast path: `--env` at deploy
+
+Most users want to ship a `.env` alongside the workflow:
+
+```bash
+zibby workflow deploy my-pipeline --env .env
+```
+
+The CLI deploys the workflow as usual, then syncs the `.env` into per-workflow env vars. You'll see:
+
+```
+✔ Deployed my-pipeline (v1)
+✔ Bundle ready (78s)
+✔ Synced 4 env vars from .env
+```
+
+Multiple files merge with later wins (mirrors how dotenv libraries usually layer):
+
+```bash
+zibby workflow deploy my-pipeline --env .env --env .env.prod
+```
+
+## Manage after deploy: `zibby workflow env`
+
+Four verbs, all keyed by the workflow UUID (from `zibby workflow 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
+```
+
+`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.
+
+`list` only returns key names, never values. Once you set a value, the only place it surfaces is inside the running container.
+
+### Examples
+
+Rotate one key:
+```bash
+zibby workflow env set 1a255ded-9f57-44ad-81cf-70726b13d653 ANTHROPIC_API_KEY=sk-ant-rotated
+```
+
+Wipe all env on a workflow (push an empty file):
+```bash
+zibby workflow 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
+  env:
+    ANTHROPIC_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    WORKFLOW_UUID: ${{ vars.WORKFLOW_UUID }}
+    ZIBBY_API_KEY: ${{ secrets.ZIBBY_API_KEY }}
+```
+
+## Resolution order at trigger time
+
+When a Fargate task starts, env vars come from three layers (later wins):
+
+```
+built-in container vars  →  project secrets (DDB)  →  workflow 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.
+
+## Validation
+
+| Field | Rule |
+|---|---|
+| Key name | Must match `^[A-Z_][A-Z0-9_]*$` (uppercase letters, digits, underscores; can't start with a digit). Bash-compatible. |
+| 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.
+
+## Use case: multi-agent workflows
+
+Different nodes in the same workflow may want to call different model vendors:
+
+```js
+// graph.mjs
+graph
+  .addNode('plan',      { prompt, outputSchema: Plan,   agent: 'claude' })  // uses ANTHROPIC_API_KEY
+  .addNode('implement', { prompt, outputSchema: Diff,   agent: 'cursor' })  // uses CURSOR_API_KEY
+  .addNode('verify',    { prompt, outputSchema: Result, agent: 'codex'  }); // uses OPENAI_API_KEY
+```
+
+Drop the three keys into `.env`, deploy:
+
+```bash
+cat > .env <<EOF
+ANTHROPIC_API_KEY=sk-ant-...
+CURSOR_API_KEY=key_...
+OPENAI_API_KEY=sk-...
+EOF
+
+zibby workflow deploy multi-agent --env .env
+```
+
+Each agent reads its own env var when invoked. No prompt-stuffing keys, no per-node config.
+
+## 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.
+- **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.
+
+## 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 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.
+
+## HTTP API (advanced / scripting)
+
+If you can't use the CLI (e.g. inline server-side trigger, similar to `triggering.md`'s webhook section), the routes are exposed directly:
+
+```
+GET    /workflows/{uuid}/env
+PUT    /workflows/{uuid}/env       body: {"env": {"KEY": "value", ...}}
+PATCH  /workflows/{uuid}/env/{key} body: {"value": "..."}
+DELETE /workflows/{uuid}/env/{key}
+```
+
+Auth is `Bearer` (session JWT or `ZIBBY_API_KEY`). Host is `https://api-prod.zibby.app`. There is no `/v1` prefix.
+
+For everything else, use the CLI — it's the supported public surface and handles auth + UUID resolution + error messages for you.

package/docs/cloud/limits.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 4
+title: Limits & quotas
+---
+
+# Limits & quotas
+
+## Workflow runtime cap
+
+Every workflow execution has a **30-minute hard cap**. If a workflow 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)
+  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
+
+If your workflow 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
+- Contact us about a Pro tier with a longer cap
+
+The cap is enforced **inside** the container by a watchdog timer set on startup,
+so it works even if the AWS-side controls fail.
+
+## Per-execution resource budget
+
+| Resource | Limit |
+|---|---|
+| Runtime | 30 min |
+| CPU | 1 vCPU |
+| Memory | 2 GB |
+| Disk | 20 GB ephemeral |
+| Outbound bandwidth | Unmetered |
+
+If you hit memory or CPU limits, the container is OOM-killed and the execution is
+marked failed.
+
+## Container freedom (what you CAN do)
+
+Inside your container, your workflow 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)
+- Spawn child processes
+- Read/write files in `/workspace`
+- Use the full CPU/memory budget for compute
+
+Your code runs in an isolated Fargate task — no shared state with other customers,
+no side effects on Zibby infrastructure.
+
+## What you CAN'T do
+
+| Boundary | Why |
+|---|---|
+| Talk to other customers' workflows | 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 |
+| Persist state between runs | Containers are ephemeral — use S3 or your DB for state |
+
+## Outbound network
+
+By default your workflow 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).
+
+## Rate limits
+
+| Endpoint | Limit |
+|---|---|
+| Trigger workflow | 60/min per account |
+| Read logs | 600/min per account |
+| Deploy workflow | 30/hour per account |
+
+Hitting a rate limit returns `429 Too Many Requests` with a `Retry-After` header.

package/docs/cloud/logs.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 2
+title: Logs
+---
+
+# Logs
+
+Cloud workflow runs stream to CloudWatch in real time. The CLI exposes them via Server-Sent Events (SSE) — `zibby workflow logs <uuid> -t` is a thin client over that.
+
+## Tail live
+
+```bash
+zibby workflow logs <uuid> -t
+```
+
+What you see:
+
+```
+  Streaming logs for workflow 2b1ea07f-3ede-4bfd-a51d-431f0bab008e...
+  Press Ctrl+C to stop.
+
+2026-05-02 23:30:51.345  zibby v0.1.x
+────────────────────────────────────────────────────────────
+ Workflow:  my-pipeline
+ Job:       ee333411-...
+ Project:   6b60049d-...
+ Agent:     cursor (model: auto)
+────────────────────────────────────────────────────────────
+[setup] Bundle extracted (3.2s)
+[setup] Loaded MyPipelineWorkflow
+[setup] Registered 5 agent strategies (...)
+
+┌ example
+│ ◆ Model: auto | key: ***bc97
+│ Prompt sent to LLM:
+│ ...
+│ ◆ status: warn
+└ done 19.4s
+[done] my-pipeline completed in 19.4s
+```
+
+## Heroku-style follow
+
+UUID is a *workflow* identifier, not an execution identifier. With `-t`, after one execution finishes the stream waits for the next trigger of the same workflow and auto-switches:
+
+```
+  Waiting for next execution...
+
+  ┌─ Execution: cd1f55d5...43d7 (task: 3b85ee3a)
+  └─ Streaming logs...
+
+(streams the new execution)
+```
+
+Ctrl+C to exit. There's no "exit on completion" mode — if you only want logs from one specific run, dump (without `-t`):
+
+```bash
+zibby workflow logs <uuid>
+```
+
+## Reconnects
+
+The SSE client reconnects automatically on transient errors. You'll see at most one `SSE Error:` + `Reconnecting...` per outage; once recovered, `Reconnected.` is printed once and the stream continues. No spam during cold-start flap.
+
+## Past runs
+
+CloudWatch retains logs for 30 days by default. Beyond that, the per-run session folder (uploaded to S3 at the end of each execution) is the long-term archive — accessible via `zibby workflow download <uuid>`.
+
+## Programmatic access
+
+The same SSE endpoint is consumable from your own code:
+
+```js
+const eventSource = new EventSource(
+  `https://logs-stream.zibby.app/?jobId=${uuid}`,
+  { headers: { Authorization: `Bearer ${apiKey}` } }
+);
+
+eventSource.addEventListener('log', (e) => {
+  const { timestamp, message } = JSON.parse(e.data);
+  console.log(timestamp, message);
+});
+
+eventSource.addEventListener('complete', () => {
+  console.log('Run finished');
+  eventSource.close();
+});
+```
+
+Or use the polling endpoint for batch retrieval:
+
+```bash
+GET /v1/workflows/<uuid>/logs?lines=1000&since=<unix-ms>
+```
+
+## Filtering by job ID
+
+`uuid` matches the workflow. To pin to a specific execution, pass the job ID instead:
+
+```bash
+zibby workflow logs <jobId>
+```
+
+The CLI auto-detects: if it's an execution row, you stream that one. If it's a workflow row, you get follow-mode.

package/docs/cloud/triggering.md

@@ -0,0 +1,114 @@
+---
+sidebar_position: 1
+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:
+
+```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
+```
+
+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.
+
+## CI / cron
+
+Anywhere you can shell out, call the CLI. Don't hand-roll an HTTP client — you'll just rebuild what the CLI already does (project lookup from UUID, idempotency, quota error messages, retries).
+
+### GitHub Actions
+
+```yaml
+- name: Trigger Zibby workflow
+  run: |
+    npm i -g @zibby/cli
+    zibby workflow 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 }}
+```
+
+### Cron (any provider)
+
+GitHub Actions schedule, Vercel Cron, EventBridge with a Lambda runner, fly.io machines — all the same pattern:
+
+```yaml
+on:
+  schedule:
+    - cron: '0 9 * * 1'   # every Monday 9am UTC
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm i -g @zibby/cli
+      - run: zibby workflow trigger $UUID --input '{"weekly":true}'
+        env:
+          UUID: ${{ vars.WORKFLOW_UUID }}
+          ZIBBY_API_KEY: ${{ secrets.ZIBBY_API_KEY }}
+```
+
+### Webhook handlers
+
+Inside a Node/Python/Go server processing an inbound webhook (Stripe, GitHub, Linear), spawn the CLI from your handler. You inherit all of its behavior — auth, error handling, idempotency — and don't write any of it yourself.
+
+```js
+import { execFileSync } from 'node:child_process';
+
+app.post('/webhook', (req, res) => {
+  if (!verifySignature(req)) return res.status(401).end();
+
+  try {
+    execFileSync('zibby', [
+      'workflow', 'trigger', process.env.WORKFLOW_UUID,
+      '--input', JSON.stringify(req.body),
+      '--idempotency-key', req.headers['x-event-id'],
+    ], { env: process.env, stdio: 'pipe' });
+    res.status(202).end();
+  } catch (err) {
+    res.status(502).end();
+  }
+});
+```
+
+If your runtime can't spawn a Node CLI (constrained Lambda layers, edge runtimes, non-Node servers without child_process), open an issue — that's the case worth a real SDK, not a documented HTTP surface.
+
+## Idempotency
+
+Pass an idempotency key to deduplicate triggers within a 24-hour window:
+
+```bash
+zibby workflow trigger <uuid> \
+  -p ticket=BUG-123 \
+  --idempotency-key webhook-2026-05-02-event-7
+```
+
+Same key + same input within 24h returns the original `jobId` instead of starting a new run. Use the inbound event's ID (`X-Event-Id`, Stripe's `event.id`, GitHub's delivery ID) — that way a retry from the source automatically dedupes.
+
+## Tailing the result
+
+After triggering, the CLI prints the `jobId`. To watch the execution:
+
+```bash
+zibby workflow logs <uuid> -t
+```
+
+See [`workflow logs` in the CLI Reference](../cli-reference#workflow-logs).
+
+## Per-workflow 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.
+
+## Quotas
+
+Per-project quota:
+- Concurrent executions
+- Total executions per day
+- Per-execution wall-clock cap (default: 30 min)
+
+Hit a quota and the trigger errors out with a readable message + retry hint. The CLI surfaces these directly; if you're shelling out from CI, the non-zero exit + stderr is enough to fail the job and have your retry logic kick in.

package/docs/concepts/agents.md

@@ -0,0 +1,112 @@
+---
+sidebar_position: 2
+title: Agent strategies
+---
+
+# Agent strategies
+
+A **strategy** is the bridge between a node and a real coding-agent CLI. The framework ships with five built-in strategies; you can also write your own.
+
+## Built-ins
+
+| Strategy | Backed by | When to pick it |
+|---|---|---|
+| `cursor` | `cursor-agent` CLI | Fast, file-aware, great default for code tasks |
+| `claude` | `@anthropic-ai/claude-agent-sdk` | Best reasoning, deep tool-use loops, large context |
+| `codex` | `@openai/codex` CLI | Strong general-purpose, good for verification nodes |
+| `gemini` | `@google/gemini-cli` | When you specifically want Gemini's behavior |
+| `assistant` | OpenAI Assistants API | Stateful conversations, retrieval, file uploads |
+
+## Selecting per node
+
+Two ways:
+
+```js
+// 1. Per-node config — wins over everything else
+graph.addNode('plan', { prompt, outputSchema, agent: 'claude' });
+
+// 2. Project default — falls through if no per-node override
+// .zibby.config.mjs
+export default {
+  agent: { default: 'cursor' },
+};
+```
+
+The resolution order: `node.agent` → `state.agentType` → `process.env.AGENT_TYPE` → project config default.
+
+## Models
+
+Each agent CLI has its own model selector. Override it via:
+
+```js
+// Per-node model
+graph.addNode('plan', {
+  prompt,
+  outputSchema,
+  agent: 'claude',
+  model: 'claude-opus-4-6',
+});
+
+// Or globally per-agent in .zibby.config.mjs
+export default {
+  agent: {
+    default: 'cursor',
+    claude: { model: 'claude-opus-4-6' },
+    cursor: { model: 'auto' },
+  },
+};
+```
+
+`auto` (the default for cursor/claude/gemini) uses the agent CLI's own current default — which tracks the latest stable model.
+
+## Bring your own
+
+The `AgentStrategy` base class is two methods:
+
+```js
+import { AgentStrategy, registerStrategy } from '@zibby/agent-workflow';
+
+class MyAgent extends AgentStrategy {
+  constructor() { super('mine', 'My custom agent', 100); }
+
+  canHandle(_context) {
+    return Boolean(process.env.MY_API_KEY);
+  }
+
+  async invoke(prompt, { schema, model }) {
+    const raw = await fetch('https://my.api/chat', {
+      method: 'POST',
+      body: JSON.stringify({ prompt, model: model ?? 'default' }),
+    }).then(r => r.text());
+
+    return { raw, structured: schema.parse(JSON.parse(raw)) };
+  }
+}
+
+registerStrategy(new MyAgent());
+```
+
+Then a node can use it:
+
+```js
+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.
+
+## Authentication
+
+| Strategy | Env var | Alternative |
+|---|---|---|
+| `cursor` | `CURSOR_API_KEY` | `cursor-agent login` |
+| `claude` | `ANTHROPIC_API_KEY` | — |
+| `codex` | `OPENAI_API_KEY` | — |
+| `gemini` | `GOOGLE_API_KEY` | — |
+| `assistant` | `OPENAI_API_KEY` | — |
+
+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.
+
+Workflow env wins over project secrets on conflict (last-write-wins inside the Fargate task).