@zibby/skills 0.2.23 → 0.2.24

package/docs/cloud/env-vars.md

@@ -1,144 +0,0 @@
----
-sidebar_position: 4
-title: Per-agent env vars
----
-
-# Per-agent env vars
-
-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 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 agent:
-
-```bash
-zibby agent deploy my-agent --env .env
-```
-
-The CLI deploys the agent as usual, then syncs the `.env` into per-agent env vars. You'll see:
-
-```
-✔ Deployed my-agent (v1)
-✔ Bundle ready (78s)
-✔ Synced 4 env vars from .env
-```
-
-Multiple files merge with later wins (mirrors how dotenv libraries usually layer):
-
-```bash
-zibby agent deploy my-agent --env .env --env .env.prod
-```
-
-## Manage after deploy: `zibby agent env`
-
-Four verbs, all keyed by the agent UUID (from `zibby agent list` or `.zibby-deploy.json`):
-
-```bash
-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 agent 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 agent env set 1a255ded-9f57-44ad-81cf-70726b13d653 ANTHROPIC_API_KEY=sk-ant-rotated
-```
-
-Wipe all env on an agent (push an empty file):
-```bash
-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 agent 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)  →  agent env (DDB)
-```
-
-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
-
-| 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 agent env set <uuid> lowercase=v` fails fast with a readable message instead of a 400.
-
-## Use case: multi-vendor agents
-
-Different nodes in the same agent 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 agent 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 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 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 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.
-
-## 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

@@ -1,81 +0,0 @@
----
-sidebar_position: 4
-title: Limits & quotas
----
-
-# Limits & quotas
-
-## Agent runtime cap
-
-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 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 agents
-
-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 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,
-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 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)
-- 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' 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 |
-| Persist state between runs | Containers are ephemeral — use S3 or your DB for state |
-
-## Outbound network
-
-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).
-
-## Rate limits
-
-| Endpoint | Limit |
-|---|---|
-| Trigger agent | 60/min per account |
-| Read logs | 600/min 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/logs.md

@@ -1,104 +0,0 @@
----
-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

@@ -1,128 +0,0 @@
----
-sidebar_position: 1
-title: Triggering programmatically
----
-
-# Triggering programmatically
-
-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 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 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
-
-When more than one input source is provided, they merge with this **precedence (highest → lowest)**:
-
-1. `-p key=value` (repeatable) — wins over everything; great for shell-friendly tweaks on top of a base payload
-2. `--input '<json>'` — full JSON payload as a string
-3. `--input-file path.json` — full JSON/YAML payload from a file (lowest 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 agent trigger <uuid> --input-file payload.json -p priority=urgent
-```
-
-## 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 agent
-  run: |
-    npm i -g @zibby/cli
-    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 }}
-```
-
-### 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 agent 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', [
-      'agent', '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 agent 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 agent logs <uuid> -t
-```
-
-See [`agent logs` in the CLI Reference](../cli-reference#agent-logs).
-
-## Per-agent env vars
-
-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
-
-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

@@ -1,112 +0,0 @@
----
-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 agent 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 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.
-
-Agent env wins over project secrets on conflict (last-write-wins inside the Fargate task).