@zibby/skills 0.1.10 → 0.1.12

package/docs/cli-reference.md

@@ -1,338 +1,202 @@
 ---
-sidebar_position: 6
+sidebar_position: 4
 title: CLI Reference
 ---
 
 # CLI Reference
 
-## Installation
+Every command lives under `zibby workflow <verb>` for consistency. The bare top-level forms (`zibby start`, `zibby deploy`, `zibby trigger`, `zibby logs`, `zibby g workflow`) are kept as backward-compat aliases — they call the same handlers — but new code should use the namespaced forms.
 
-```bash
-npm install -g @zibby/cli
-```
-
----
-
-## Commands
-
-### `zibby test [spec-path]`
-
-Run a test specification.
-
-```bash
-# Run a local test spec
-zibby test test-specs/login.txt --agent cursor
-
-# Run without any project setup
-echo "Go to example.com" > test.txt && zibby test test.txt --agent cursor
-
-# Run with cloud sync
-zibby test test-specs/login.txt --sync
+## Workflow commands
 
-# Run test cases from cloud
-zibby test --sources TC001,TC002 --execution abc123
-```
-
-| Flag | Description |
+| Command | What it does |
 |---|---|
-| `--agent <type>` | AI agent: `cursor`, `claude`, or `codex` |
-| `--workflow <name>` | Workflow to use (e.g., `QuickSmokeWorkflow`, `quick-smoke`) |
-| `--headless` | Run browser in headless mode |
-| `--node <name>` | Run only a specific node (`preflight`, `execute_live`, `generate_script`) |
-| `--session <id>` | Reuse an existing session (`last` for most recent) — requires `--node` |
-| `--sources <ids>` | Comma-separated test case IDs to fetch from cloud |
-| `--execution <id>` | Execution ID (required with `--sources`) |
-| `--project <id>` | Project ID or API token (auto-detected from `ZIBBY_API_KEY`) |
-| `--collection <id-or-name>` | Collection to organize the run into (creates if name is new) |
-| `--folder <path>` | Folder within the collection |
-| `--sync` | Force upload results to cloud |
-| `--no-sync` | Skip cloud upload |
-| `--config <path>` | Config file path (default: `.zibby.config.js`) |
-| `--auto-approve` | Auto-approve MCP tool calls (for CI/CD) |
-| `-o, --open` | Open results in browser after upload |
-| `--verbose` | Show info-level logs |
-| `--debug` | Show debug-level logs |
-
----
-
-### `zibby init [project-name]`
-
-Initialize a Zibby project with config and workflow files. **Optional** — `zibby test` works without it using the built-in workflow.
-
-```bash
-zibby init
-zibby init my-project --agent cursor --cloud-sync
-```
-
-| Flag | Description |
+| [`zibby workflow new <name>`](#workflow-new) | Scaffold a new custom workflow under `.zibby/workflows/<name>/`. |
+| [`zibby workflow run <name>`](#workflow-run) | One-shot local execution. Same input flags as `trigger`. |
+| [`zibby workflow list`](#workflow-list) | List local + deployed workflows. |
+| [`zibby workflow deploy [name]`](#workflow-deploy) | Deploy to Zibby Cloud. Interactive picker if name omitted. |
+| [`zibby workflow trigger [uuid]`](#workflow-trigger) | Run a deployed workflow remotely. UUID is canonical. |
+| [`zibby workflow logs [uuid] -t`](#workflow-logs) | Tail logs from a run, Heroku-style. |
+| [`zibby workflow download <uuid>`](#workflow-download) | Pull a deployed workflow back to local. Edit + redeploy. |
+| [`zibby workflow delete <uuid>`](#workflow-delete) | Delete a deployed workflow. |
+| [`zibby workflow start <name>`](#workflow-start) | Long-lived dev server (Studio integration). Most users want `run`. |
+| [`zibby workflow env <verb>`](#workflow-env) | Manage per-workflow encrypted env vars: `list`, `set`, `unset`, `push`. |
+
+Plus auth + admin:
+
+| Command | What it does |
 |---|---|
-| `--agent <type>` | `cursor`, `claude`, or `codex` |
-| `--cloud-sync` | Enable cloud sync |
-| `--headless` | Headless browser mode |
-| `--headed` | Headed browser mode |
-| `--api-key <key>` | Zibby API key |
-| `--skip-install` | Skip `npm install` |
-| `-f, --force` | Overwrite existing config |
+| `zibby login` | OAuth in browser. Writes session to `~/.zibby/config.json`. |
+| `zibby logout` | Clear session. |
+| `zibby status` | Show current auth state. |
+| `zibby project list` | List projects you have access to. |
 
----
-
-### `zibby login`
-
-Authenticate with Zibby (opens browser for OAuth).
+## workflow new {#workflow-new}
 
 ```bash
-zibby login
+zibby workflow new [name]
 ```
 
----
+Scaffolds `.zibby/workflows/<name>/` with a starter `graph.mjs`, `nodes/example.mjs`, `package.json`, and `workflow.json` manifest. Auto-runs `npm install` in the new folder unless `--skip-install`.
 
-### `zibby logout`
+Options:
+- `--skip-install` — skip `npm install`
+- If `name` is omitted, the CLI generates one (`zealous-otter`, etc.)
 
-Clear saved session.
+## workflow run {#workflow-run}
 
 ```bash
-zibby logout
+zibby workflow run <workflow-name>
 ```
 
----
-
-### `zibby status`
-
-Show current authentication status.
-
-```bash
-zibby status
-zibby status --json
-```
-
----
+Loads `graph.mjs`, instantiates the entry class, runs the graph **once** in-process, prints results, and exits. Output → `.zibby/output/sessions/<sessionId>/`.
 
-### `zibby list`
+Mirrors `zibby workflow trigger` so the same input flags work locally and in the cloud — flip the verb and the project, and your local dev loop is exactly the same call shape your CI/CD uses.
 
-List your projects and API tokens.
+Options:
+- `-p, --param <key=value>` — input param (repeatable, highest precedence). Example: `-p ticket=BUG-123 -p priority=high`
+- `--input <json>` — input as JSON string
+- `--input-file <path>` — input as JSON file (lowest precedence)
 
+Examples:
 ```bash
-zibby list
+zibby workflow run my-pipeline
+zibby workflow run my-pipeline -p ticket=BUG-123
+zibby workflow run my-pipeline --input '{"ticket":"BUG-123","priority":"high"}'
+zibby workflow run my-pipeline --input-file payload.json -p priority=urgent
 ```
 
----
-
-### `zibby upload <spec-path>`
-
-Upload existing test artifacts to Zibby Cloud.
-
-```bash
-zibby upload test-specs/login.txt --collection "Auth Tests"
-```
-
-| Flag | Description |
-|---|---|
-| `--project <id>` | Project ID (required) |
-| `--collection <id-or-name>` | Collection to upload into |
-| `--folder <path>` | Folder within collection |
-
----
-
-### `zibby video`
-
-Organize test videos — moves videos from `test-results/` to sit next to test files.
+## workflow start {#workflow-start}
 
 ```bash
-zibby video
+zibby workflow start <workflow-name>
 ```
 
----
+Long-lived local dev server (default port 3848). Listens on `POST /trigger` for input payloads and runs the workflow in-process. Used today by the Studio desktop app — for plain CLI use, prefer `workflow run`.
 
-### `zibby setup-playwright`
+Options:
+- `-p, --port <port>` — override the default port (3848)
 
-Configure the Playwright MCP server.
+## workflow list {#workflow-list}
 
 ```bash
-zibby setup-playwright
-zibby setup-playwright --headed --viewport-width 1920 --viewport-height 1080
+zibby workflow list
 ```
 
----
+Shows both local workflows (folders under `.zibby/workflows/`) and deployed ones (from cloud, scoped to projects you have access to). Output is a table with UUID, Name, Project, Version. `-` in any column means "not applicable" (e.g. local-only workflows have no UUID yet).
 
-### `zibby ci-setup`
+Options:
+- `--local-only` — skip the cloud query
+- `--remote-only` — skip the local scan
+- `--project <id>` — filter to one project
 
-Configure Cursor Agent for CI/CD pipelines.
+## workflow deploy {#workflow-deploy}
 
 ```bash
-zibby ci-setup
-zibby ci-setup --get-keys
-zibby ci-setup --save
+zibby workflow deploy [workflow-name]
 ```
 
----
-
-### `zibby g workflow [name]`
-
-Scaffold a new custom workflow. Auto-generates a name if omitted.
-
-```bash
-zibby g workflow ticket-triage
-zibby g workflow                   # auto-generates name
-```
+Two phases:
+1. Upload sources to S3 (presigned PUT). The CLI also resolves your `.zibby.config.mjs` (if present at project root) and includes it in the bundle as `zibby.config.json` — see [Bundle build](./cloud/bundles).
+2. CodeBuild downloads, runs `npm install --omit=dev`, packages a tarball, uploads it. The tarball is what each cloud execution downloads at trigger time.
 
----
+After success, the CLI writes `.zibby/workflows/<name>/.zibby-deploy.json` with the canonical UUID. Commit this file.
 
-### `zibby start <workflow-name>`
+Options:
+- `--project <id>` — skip the project picker
+- `--api-key <key>` — auth via API key (or set `ZIBBY_API_KEY`)
+- `--env <path>` — sync a `.env` file into per-workflow env vars after deploy. Repeatable (later files override). See [Per-workflow env vars](./cloud/env-vars).
+- `--verbose` — show raw CodeBuild logs during the bundle build
 
-Start a local dev server for testing a custom workflow.
+## workflow trigger {#workflow-trigger}
 
 ```bash
-zibby start ticket-triage
-zibby start ticket-triage --port 3850
+zibby workflow trigger <uuid>
 ```
 
-| Flag | Description |
-|---|---|
-| `-p, --port <port>` | Server port (default: 3848) |
-
----
+UUID is required (or omit for interactive picker). Names aren't accepted — pass the UUID from `.zibby-deploy.json` or `workflow list`.
 
-### `zibby deploy <workflow-name>`
+Options:
+- `-p, --param <key=value>` — input param (repeatable, highest precedence)
+- `--input <json>` — input as JSON string
+- `--input-file <path>` — input as JSON/YAML file (lowest precedence)
+- `--idempotency-key <key>` — prevent duplicate executions
+- `--api-key <key>` — auth via API key
 
-Deploy a custom workflow to Zibby Cloud. Returns the trigger URL and workflow UUID.
+## workflow logs {#workflow-logs}
 
 ```bash
-zibby deploy ticket-triage --project <id>
+zibby workflow logs <uuid>          # dump latest run
+zibby workflow logs <uuid> -t       # tail live (Heroku-style)
 ```
 
-| Flag | Description |
-|---|---|
-| `--project <id>` | Project ID (or `ZIBBY_PROJECT_ID` env) |
-| `--api-key <key>` | API key (or `ZIBBY_API_KEY` env, or session token) |
+When `-t` is set and the workflow finishes, the stream waits for the next trigger of the same workflow and auto-switches to streaming it. Ctrl+C to exit.
 
----
+Options:
+- `-t, --follow` — live tail
+- `--lines <n>` — max log lines per fetch (default: 500)
+- `--all --workflow <name>` — interleaved logs from all runs (requires `--workflow`)
+- `--api-key <key>` — auth via API key
 
-### `zibby trigger <workflow-uuid>`
+**Storage & retention.** Live logs are kept in CloudWatch for 30 days. Beyond that, the per-run session folder (uploaded to S3 at the end of every execution) is the long-term archive — pull it back with `zibby workflow download <uuid>`.
 
-Trigger a deployed workflow by its UUID. The CLI automatically discovers the project.
+## workflow env {#workflow-env}
 
-```bash
-# Trigger by UUID (project auto-discovered)
-zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405
-
-# Trigger by UUID with input data
-zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405 \
-  --input '{"ticket":"JIRA-123"}'
-
-# Trigger by name (requires project)
-zibby trigger custom-flow --project <id>
-
-# With idempotency key (prevents duplicate runs)
-zibby trigger 562e48d7-ef67-4900-96b7-0d7b51a33405 \
-  --idempotency-key "daily-scan-2026-04-27"
-```
-
-| Flag | Description |
-|---|---|
-| `--input <json>` | Input data as JSON string |
-| `--idempotency-key <key>` | Prevent duplicate executions (same key within 24h) |
-| `--project <id>` | Project ID (only needed if triggering by workflow name) |
-
-**After triggering, stream logs:**
+Per-workflow encrypted env vars — KMS-stored on the workflow record, injected into the Fargate task at trigger time. Workflow env wins over project secrets on conflict.
 
 ```bash
-zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405 -t
+zibby workflow env list <uuid>                       # show key names (no values)
+zibby workflow env set <uuid> ANTHROPIC_API_KEY=sk-…  # add or rotate one
+zibby workflow env unset <uuid> OLD_KEY               # remove one
+zibby workflow env push <uuid> --file .env [--file .env.prod]   # bulk replace from .env files
 ```
 
----
+`push` accepts repeatable `--file` (later files override). `list` only ever returns key names — values never leave the encrypted blob.
 
-### `zibby logs <workflow-uuid>`
+The shortcut for first-time setup is `zibby workflow deploy --env .env`, which runs `push` automatically against the new UUID. Full guide: [Per-workflow env vars](./cloud/env-vars).
 
-Fetch and display logs from a workflow's latest execution.
+## workflow download {#workflow-download}
 
 ```bash
-# Fetch logs for latest execution (simple, one-time fetch)
-zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405
-
-# Stream logs in real-time (like "heroku logs -t")
-zibby logs 562e48d7-ef67-4900-96b7-0d7b51a33405 -t
-
-# Stream logs by workflow name
-zibby logs --workflow custom-flow --project <id> -t
+zibby workflow download <uuid>
 ```
 
-| Flag | Description |
-|---|---|
-| `-t, --follow` | Stream logs in real-time via SSE (Server-Sent Events) |
-| `--project <id>` | Project ID (optional, auto-discovered from workflow UUID) |
-| `--workflow <name>` | Workflow name (fetches latest run) |
-| `--all` | Interleaved logs from all runs (requires `--workflow`) |
-| `--lines <n>` | Max log lines per fetch (default: 1000) |
-
-**How it works:**
-
-- **Without `-t`**: Fetches complete logs from CloudWatch (permanent storage) and exits. Perfect for historical logs and debugging old executions.
-- **With `-t`**: Streams logs in real-time via SSE from DynamoDB hot cache (24h TTL). Only works for active/recent executions. Press Ctrl+C to stop.
+Pulls the deployed workflow's sources back into `.zibby/workflows/<name>/`, including the `.zibby-deploy.json` manifest. Useful when collaborators need the source from cloud.
 
-**Architecture:**
+Options:
+- `--type <type>` — for built-in workflows (`analysis`, `implementation`, `run_test`)
+- `--output <dir>` — alternate output base
+- `--include-default` — pull the built-in default graph if no custom one exists
 
-```
-CloudWatch Logs (permanent) ──────────> CLI (without -t)
-     │
-     └──> Kinesis ──> Lambda ──> DynamoDB (24h TTL) ──> SSE ──> CLI (with -t)
-```
-
----
-
-### `zibby workflow download`
-
-Download a workflow graph from Zibby Cloud.
+## workflow delete {#workflow-delete}
 
 ```bash
-zibby workflow download --type run_test
+zibby workflow delete <uuid>
 ```
 
-### `zibby workflow list`
+Removes the workflow from cloud (and its trigger URL). Local files are not touched.
 
-List all workflows for a project.
+## Environment variables
 
-```bash
-zibby workflow list
-```
+| Var | Purpose |
+|---|---|
+| `ZIBBY_API_KEY` | API key for non-interactive auth (CI). Preferred over saved session. |
+| `ZIBBY_PROJECT_ID` | Default project for commands that take `--project` |
+| `AGENT_TYPE` | Default agent strategy when no per-node override and no project default |
+| `ZIBBY_DEPLOY_VERBOSE=1` | Same as `--verbose` on `workflow deploy` |
+| `ZIBBY_SESSION_LOG=1` | Re-enable the diagnostic `[zibby:session]` log line in run output |
+| `ZIBBY_RUN_DIAG=1` | Cloud runtime: dump per-copy `agent-workflow` registry state |
+| `ZIBBY_DEBUG=true` | Verbose debug logs from the framework |
 
----
+## Legacy aliases
 
-## Environment Variables
+These still work and route to the same handlers, but new code should use the `zibby workflow <verb>` form:
 
-| Variable | Description |
+| Legacy | Canonical |
 |---|---|
-| `CURSOR_API_KEY` | Cursor agent API key (required in CI, optional locally) |
-| `ANTHROPIC_API_KEY` | Claude agent API key |
-| `OPENAI_API_KEY` | Codex agent API key |
-| `ZIBBY_API_KEY` | Project API key for cloud sync (from dashboard Settings) |
-| `ZIBBY_USER_TOKEN` | Personal Access Token for CI/CD uploads |
-| `ZIBBY_ENV` | Environment override: `local`, `staging`, `prod` |
-
-## Configuration File
-
-`.zibby.config.js` in your project root (ESM):
-
-```javascript
-export default {
-  agent: {
-    cursor: { model: 'auto' },
-    // claude: { model: 'auto' },
-    // codex: { model: 'gpt-5.2-codex' },
-  },
-
-  paths: {
-    specs: 'test-specs',
-    generated: 'tests',
-    output: '.zibby/output',
-  },
-
-  context: {
-    filenames: ['CONTEXT.md', 'AGENTS.md'],
-  },
-
-  video: 'on',
-  viewport: { width: 1280, height: 720 },
-  playwrightArtifacts: true,
-  cloudSync: false,
-};
-```
+| `zibby g workflow <name>` | `zibby workflow new <name>` |
+| `zibby start <name>` | `zibby workflow start <name>` |
+| `zibby run <name>` | `zibby workflow run <name>` |
+| `zibby deploy [name]` | `zibby workflow deploy [name]` |
+| `zibby trigger <uuid>` | `zibby workflow trigger <uuid>` |
+| `zibby logs <uuid>` | `zibby workflow logs <uuid>` |

package/docs/cloning-repositories.md

@@ -269,7 +269,7 @@ Common failure reasons:
 
 ## Local Development
 
-When running workflows locally (`zibby start`), you'll need to:
+When running workflows locally (`zibby workflow 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 start my-workflow
+zibby workflow run my-workflow
 ```
 
 In production (cloud), these are injected automatically.

package/docs/cloud/bundles.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 3
+title: Bundle build (Heroku-style)
+---
+
+# Bundle build
+
+When you `zibby workflow 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.
+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.
+
+## What's in the bundle
+
+The CLI uploads:
+
+| File | Source | What it does |
+|---|---|---|
+| `graph.mjs` | `.zibby/workflows/<name>/graph.mjs` | The workflow definition. Required. |
+| `nodes/*.mjs` | `.zibby/workflows/<name>/nodes/` | Per-node logic. Optional. |
+| `workflow.json` | `.zibby/workflows/<name>/workflow.json` | Manifest (entry class, triggers). Optional. |
+| `package.json` + `package-lock.json` | `.zibby/workflows/<name>/` | Dependency resolution. Required when graph.mjs imports `@zibby/*`. |
+| `zibby.config.json` | resolved from `.zibby.config.mjs` at project root | Your config (`agent`, `models`, `browser`, …) serialized to JSON. Optional. |
+
+`zibby.config.json` is **resolved locally at deploy time** — the CLI imports your `.zibby.config.mjs`, runs any expressions in it (e.g. `process.env.X`), then `JSON.stringify`s the result. The cloud never executes user JS to load config; it just reads the JSON. Function values are dropped silently — config is data, not code.
+
+This is what makes per-node `models` overrides actually work in cloud:
+
+```js
+// .zibby.config.mjs
+export default {
+  agent: { cursor: { model: 'auto' } },
+  models: {
+    default: 'auto',
+    execute_live: 'claude-opus-4.6',  // overrides JUST the execute_live node
+  },
+};
+```
+
+## 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:
+
+```
+trigger → tarball download (3s) → graph.run() → done
+```
+
+3-second cold start instead of 60.
+
+## Spinner output
+
+```
+⠋ Building bundle on Zibby Cloud... (provisioning) — 14s
+⠙ Building bundle on Zibby Cloud... [1/4] Downloading sources — 22s
+⠹ Building bundle on Zibby Cloud... [2/4] Materializing source files — 24s
+⠸ Building bundle on Zibby Cloud... [3/4] Installing dependencies — 32s
+⠴ Building bundle on Zibby Cloud... [4/4] Packaging bundle — 56s
+✔ Bundle ready (78s) — runtime npm install eliminated
+```
+
+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.
+
+## 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.
+
+## 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.
+
+## 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:
+
+```
+[setup] Bundle extract failed (...); falling back to source install
+[setup] Workflow v3 — 6 source files
+[setup] Wrote 6 files
+[setup] Installing dependencies...
+```
+
+The fallback exists so a deploy that never produced a bundle (e.g. CodeBuild job hadn't completed yet) still works.