@zibby/skills 0.2.22 → 0.2.24

package/docs/cloning-repositories.md

@@ -1,285 +0,0 @@
----
-sidebar_position: 8
-title: Cloning Repositories
----
-
-# Cloning Repositories in Custom Agents
-
-Custom agents can clone your project's configured repositories (GitHub/GitLab) using the `cloneRepo()` helper function from `@zibby/core`.
-
-## Overview
-
-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
-
-The `cloneRepo()` function handles authentication, supports multiple repos, and works with both GitHub.com and self-hosted GitLab instances.
-
-## Basic Usage
-
-### Clone All Repositories
-
-By default, `cloneRepo()` clones all repositories configured for your project:
-
-```javascript
-// nodes/setup.mjs
-import { cloneRepo, z } from '@zibby/core';
-
-const SetupOutputSchema = z.object({
-  repoPaths: z.record(z.string()),
-});
-
-export const setupNode = {
-  name: 'setup',
-  
-  async preProcess(state) {
-    // Clone all repos
-    const repoPaths = await cloneRepo();
-    
-    // repoPaths = {
-    //   'myorg/backend': '/workspace/repos/myorg-backend',
-    //   'myorg/frontend': '/workspace/repos/myorg-frontend'
-    // }
-    
-    return { repoPaths };
-  },
-  
-  prompt: (state) => `Repositories cloned:
-${JSON.stringify(state.setup.repoPaths, null, 2)}
-
-Ready to analyze the codebase.`,
-  
-  outputSchema: SetupOutputSchema,
-};
-```
-
-### Clone Specific Repositories
-
-If you only need certain repositories:
-
-```javascript
-// Clone only backend repo
-const repoPaths = await cloneRepo({
-  repos: ['myorg/backend']
-});
-```
-
-### Using Cloned Repositories
-
-Access the cloned code via the returned paths:
-
-```javascript
-// nodes/analyze.mjs
-import { z } from '@zibby/core';
-
-const AnalyzeOutputSchema = z.object({
-  summary: z.string(),
-  files: z.array(z.string()),
-});
-
-export const analyzeNode = {
-  name: 'analyze',
-  
-  prompt: (state) => `Analyze the codebase.
-
-Repositories are cloned at:
-${JSON.stringify(state.setup.repoPaths, null, 2)}
-
-Use the Shell tool to:
-1. List files in the repos (e.g., ls ${Object.values(state.setup.repoPaths)[0]})
-2. Read important files (e.g., cat ${Object.values(state.setup.repoPaths)[0]}/README.md)
-3. Run analysis commands (e.g., cd ${Object.values(state.setup.repoPaths)[0]} && npm audit)
-
-Return a summary and list of key files.`,
-  
-  outputSchema: AnalyzeOutputSchema,
-};
-```
-
-## Configuration Options
-
-```javascript
-await cloneRepo({
-  // Clone specific repos only (default: all repos)
-  repos: ['myorg/backend', 'myorg/frontend'],
-  
-  // Base directory for cloned repos (default: '/workspace/repos')
-  baseDir: '/workspace/repos',
-  
-  // Clone depth - 1 for shallow clone, 0 for full history (default: 1)
-  depth: 1,
-  
-  // Specific branch to clone (default: repo's default branch)
-  branch: 'develop',
-});
-```
-
-## Return Value
-
-`cloneRepo()` returns an object mapping repository names to their cloned paths:
-
-```javascript
-{
-  'myorg/backend': '/workspace/repos/myorg-backend',
-  'myorg/frontend': '/workspace/repos/myorg-frontend'
-}
-```
-
-If a repository fails to clone, its value will be `null`:
-
-```javascript
-{
-  'myorg/backend': '/workspace/repos/myorg-backend',
-  'myorg/broken-repo': null  // Failed to clone
-}
-```
-
-## Complete Example Agent
-
-Here's a full agent that clones repos and runs analysis:
-
-```javascript
-// graph.mjs
-import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
-import { setupNode, analyzeNode, reportNode } from './nodes/index.mjs';
-
-export class CodeAuditWorkflow extends WorkflowAgent {
-  buildGraph() {
-    const graph = new WorkflowGraph();
-
-    graph.addNode('setup', setupNode);
-    graph.addNode('analyze', analyzeNode);
-    graph.addNode('report', reportNode);
-
-    graph.setEntryPoint('setup');
-    graph.addEdge('setup', 'analyze');
-    graph.addEdge('analyze', 'report');
-    graph.addEdge('report', 'END');
-
-    return graph;
-  }
-}
-```
-
-```javascript
-// nodes/setup.mjs
-import { cloneRepo, z } from '@zibby/core';
-
-export const setupNode = {
-  name: 'setup',
-  
-  async preProcess(state) {
-    console.log('Cloning repositories...');
-    const repoPaths = await cloneRepo();
-    console.log('Cloned:', Object.keys(repoPaths).length, 'repositories');
-    return { repoPaths };
-  },
-  
-  prompt: () => 'Repositories cloned successfully. Ready for analysis.',
-  
-  outputSchema: z.object({
-    ready: z.boolean().default(true),
-  }),
-};
-```
-
-```javascript
-// nodes/analyze.mjs
-import { z } from '@zibby/core';
-
-export const analyzeNode = {
-  name: 'analyze',
-  
-  prompt: (state) => {
-    const repoList = Object.entries(state.setup.repoPaths)
-      .map(([name, path]) => `- ${name}: ${path}`)
-      .join('\\n');
-    
-    return `Analyze all cloned repositories for security issues.
-
-Cloned repositories:
-${repoList}
-
-For each repository, use the Shell tool to:
-1. Check for dependencies with known vulnerabilities (npm audit, pip check, etc.)
-2. Search for common security issues (hardcoded secrets, SQL injection patterns, etc.)
-3. Review package.json/requirements.txt for outdated dependencies
-
-Return a comprehensive security audit report.`;
-  },
-  
-  outputSchema: z.object({
-    findings: z.array(z.object({
-      severity: z.enum(['low', 'medium', 'high', 'critical']),
-      repo: z.string(),
-      description: z.string(),
-      file: z.string().optional(),
-    })),
-    summary: z.string(),
-  }),
-};
-```
-
-## How It Works
-
-1. **Project Configuration**: You configure repositories in your project settings (Web UI)
-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 agent run gets a fresh container with no cached state
-
-## Supported Platforms
-
-- **GitHub** (github.com)
-- **GitLab** (gitlab.com)
-- **Self-hosted GitLab** (custom instance URLs from project settings)
-
-## Error Handling
-
-`cloneRepo()` is resilient to failures:
-
-```javascript
-const repoPaths = await cloneRepo();
-
-// Check for failures
-for (const [repo, path] of Object.entries(repoPaths)) {
-  if (path === null) {
-    console.error(`Failed to clone ${repo}`);
-  }
-}
-
-// Continue with successfully cloned repos
-const successfulRepos = Object.entries(repoPaths)
-  .filter(([_, path]) => path !== null);
-```
-
-Common failure reasons:
-- Missing/expired authentication tokens
-- Repository doesn't exist or access denied
-- Network issues
-- Invalid clone URL
-
-## Performance Tips
-
-1. **Shallow Clones**: Use `depth: 1` (default) for faster cloning
-2. **Specific Repos**: Only clone repos you need via the `repos` option
-3. **Parallel Execution**: `cloneRepo()` clones all repos in parallel automatically
-
-## Local Development
-
-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
-
-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 agent run my-agent
-```
-
-In production (cloud), these are injected automatically.

package/docs/cloud/bundles.md

@@ -1,92 +0,0 @@
----
-sidebar_position: 3
-title: Bundle build (Heroku-style)
----
-
-# Bundle build
-
-When you `zibby agent deploy`, two things happen:
-
-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** — agents 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 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
-```
-
-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 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 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 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 agents 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.

package/docs/cloud/dedicated-egress.md

@@ -1,140 +0,0 @@
----
-sidebar_position: 5
-title: Dedicated egress IP
----
-
-# Dedicated egress IP
-
-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 agent'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 agent exits via your dedicated IP:
-
-| What | Whether it tunnels |
-|---|---|
-| `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 |
-| 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 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.
-
-## 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/editing-prompts.md

@@ -1,79 +0,0 @@
----
-sidebar_position: 6
-title: Editing node prompts
----
-
-# Editing node prompts
-
-Every node in an agent has a **prompt** — the instructions handed to the
-coding agent when that step runs. In the graph editor (both the deploy modal
-and a deployed agent's **Overview** tab) each prompt is tagged with a badge:
-
-| Badge | What it means |
-|---|---|
-| <span style={{color:'#34d399',fontWeight:600}}>EDITABLE</span> | The prompt is a stored text template. You can change it right here. |
-| <span style={{color:'#d4b483',fontWeight:600}}>READ-ONLY</span> | The prompt is generated by the node's code at runtime. It can't be edited in the UI. |
-
-The `!` next to the badge explains the same thing on hover.
-
-## Editable prompts
-
-A prompt is editable when the node declares it as a plain text template (a
-string, optionally with `{{variables}}`).
-
-The graph shown in the marketplace **deploy modal is a read-only preview** —
-you pick the name and model there, not edit prompts. You edit editable
-prompts **after you deploy**:
-
-- Open the deployed agent's **Overview** tab.
-- Click the node, edit the prompt, and save.
-- The change applies to the next run **live — no redeploy needed**.
-
-This is the right choice when you want non-developers to tune wording,
-tone, or rules without touching code.
-
-## Read-only prompts
-
-A prompt is read-only when the node builds it **in code** — a function that
-assembles the text from state, fetched context, or conditionals at runtime.
-There's no fixed string to edit, so the editor shows a rendered preview only.
-
-To change a read-only prompt you edit the agent's source and redeploy. You
-don't need to leave your AI coding agent to do it — the
-[Zibby MCP](../packages/mcp-cli) drives the whole loop from chat:
-
-1. **Download the agent** — pull the deployed sources back to your machine.
-
-   ```bash
-   zibby agent download <uuid>
-   ```
-
-   Or, from an MCP-aware agent (Claude Code / Cursor / Codex / Gemini),
-   ask it to call `zibby_download_agent`.
-
-2. **Edit the node's code** — open the node file under
-   `.zibby/workflows/<name>/nodes/` and change how the prompt is built. Your
-   coding agent can do this directly.
-
-3. **Redeploy to update** — ship the change back to the same agent.
-
-   ```bash
-   zibby agent deploy <name>
-   ```
-
-   Or have the agent call `zibby_deploy_agent`. The deployed agent updates in
-   place; its UUID and trigger config stay the same.
-
-:::tip Want it editable instead?
-If a prompt would be better tuned by non-developers, convert the node from a
-function prompt to a **string template**. Once it's a stored template, the
-badge flips to **Editable** and it gains live-update from Overview.
-:::
-
-## Why the split exists
-
-Function prompts exist for a reason: some nodes need to assemble instructions
-from things only known at runtime — the linked ticket, the diff, prior
-reviews, whether an integration is connected. A fixed text box can't express
-that logic, so those nodes keep their prompt in code. Simpler, static prompts
-stay as editable templates so anyone can adjust them.