@superglue/cli 1.0.0 → 1.1.1

package/dist/dist/skills/superglue/SKILL.md

@@ -0,0 +1,740 @@
+---
+name: superglue
+description: "Build, test, deploy and integrate superglue tools via the sg CLI and superglue SDKs. IMPORTANT — you MUST invoke this skill and read the full reference BEFORE running ANY sg command or writing ANY superglue SDK/REST/webhook integration code. Before using the sg CLI, first check that it is installed (run sg --version; if not found, install with npm install -g @superglue/cli), then verify it is configured (check that sg init has been run or that SUPERGLUE_API_KEY and SUPERGLUE_API_ENDPOINT environment variables are set). If not, guide the user through setup first. After reading the SKILL.md file, also read the relevant references/ files for the specific topic (databases, file servers, transforms, integration/SDK)."
+---
+
+# superglue CLI (`sg`) — Agent Reference
+
+## CRITICAL RULES — READ FIRST
+
+**Authentication & Credentials:**
+
+- **Auth headers MUST be set explicitly** — credentials are NEVER auto-injected into requests
+- Every request step (in tools AND `sg system call`) must include the appropriate auth header using `<<systemId_credentialKey>>` syntax
+- OAuth systems also require explicit headers — only token refresh is automatic
+
+**Pre-Building Testing:**
+
+- **ALWAYS use `sg system call` to test endpoints BEFORE building tools**
+- Verify authentication works, understand response structure, confirm field names
+- Never guess API responses — test them first
+- This prevents 90% of tool failures
+
+**Example - `sg system call` with auth:**
+
+```bash
+sg system call --system-id notion --url "https://api.notion.com/v1/search" \
+  --method POST \
+  --headers '{"Authorization":"Bearer <<notion_access_token>>","Notion-Version":"2022-06-28"}' \
+  --body '{"filter":{"property":"object","value":"page"}}'
+```
+
+**Example - Tool step with auth:**
+
+```json
+{
+  "headers": {
+    "Authorization": "Bearer <<systemId_access_token>>"
+  }
+}
+```
+
+**Other Critical Rules:**
+
+- `systemId` goes on each step's `config`, NOT at the tool level
+- Steps execute sequentially; each step can reference previous step results
+- `id` fields must be kebab-case for tools, snake_case for systems
+- Simple `<<varName>>` only works for **top-level keys** (no dots, no nesting)
+- For nested access use arrow functions: `<<(sourceData) => sourceData.currentItem.id>>`
+- ALWAYS access step results via `.data`: `sourceData.stepId.data` not `.results`
+
+---
+
+## Installation & Setup
+
+### Prerequisites Check
+
+Before running any `sg` command, verify the CLI is installed and configured:
+
+1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install it: `npm install -g @superglue/cli`
+2. **Check config exists**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration (see below).
+
+### Installing the CLI
+
+```bash
+npm install -g @superglue/cli
+```
+
+After installation, the `sg` command is available globally.
+
+### Initialization (REQUIRED before first use)
+
+The CLI **will not work** until configured with an API key and endpoint. Without configuration, all commands fail with `fetch failed` or similar connection errors.
+
+**Option A: Interactive setup (recommended for humans)**
+
+```bash
+sg init
+```
+
+This prompts for:
+
+1. **API Key** (required) — get one at https://app.superglue.cloud/admin?view=api-keys
+2. **API Endpoint** — defaults to `https://api.superglue.cloud`
+3. **Web Endpoint** — for OAuth callbacks, auto-derived from API endpoint
+4. **Output mode** — `stdout` (default) or `stdout+file`
+5. **Config location** — project-local (`.superglue/config.json`) or global (`~/.superglue/config.json`)
+
+It verifies the connection before saving. On success it creates the config file, a `drafts/` directory, and updates `.gitignore` if using local config.
+
+**Option B: Environment variables (recommended for CI and AI agents)**
+
+If `sg init` is not practical (non-interactive environments, CI, AI agents), set these env vars instead:
+
+```bash
+export SUPERGLUE_API_KEY="your-api-key"
+export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud"  # optional, this is the default
+```
+
+With these set, all `sg` commands work without a config file.
+
+**Option C: CLI flags (per-command override)**
+
+```bash
+sg system list --api-key "your-key" --endpoint "https://api.superglue.cloud"
+```
+
+### Config Resolution Order
+
+CLI flags > environment variables > config file (local `.superglue/config.json` > global `~/.superglue/config.json`).
+
+### Verifying Setup
+
+After configuring, verify the connection works:
+
+```bash
+sg system list    # should return a list (possibly empty) without errors
+```
+
+If you see `fetch failed`, `ECONNREFUSED`, or authentication errors, double-check your API key and endpoint.
+
+---
+
+## Quick Start
+
+```bash
+sg system list                 # verify connection
+sg tool build --config '{"id":"...","instruction":"...","steps":[...]}'
+sg tool run --draft <draftId>
+sg tool save --draft <draftId>
+```
+
+## Global Flags
+
+| Flag               | Description                                 |
+| ------------------ | ------------------------------------------- |
+| `--json`           | Force JSON output (auto-enabled in non-TTY) |
+| `--api-key <key>`  | Override API key                            |
+| `--endpoint <url>` | Override API endpoint                       |
+
+---
+
+## Command Reference
+
+### `sg init`
+
+Interactive setup — API key, endpoint, output mode. Creates `.superglue/`.
+
+### Tool Commands
+
+**`sg tool build`** — Register a tool config. Returns a `draftId`. Not AI-powered — you provide the full config.
+
+```bash
+sg tool build --config tool.json                    # from file
+sg tool build --config '{"id":"...","steps":[...]}'  # inline JSON
+sg tool build --id my-tool --instruction "..." --steps steps.json --payload '{"key":"val"}'
+```
+
+| `--config <file-or-json>` | Full JSON config (file path or inline JSON string) |
+| `--id <id>` | Tool ID (kebab-case) |
+| `--instruction <text>` | Human-readable description |
+| `--steps <file>` | JSON file with steps array |
+| `--payload <json>` | Sample payload (generates inputSchema) |
+| `--file <key=path>` | Attach file reference (repeatable) |
+
+**`sg tool run`** — Execute a draft or saved tool. Streams live execution logs to the terminal.
+
+```bash
+sg tool run --draft <draftId> --payload '{"userId":"123"}'
+sg tool run --tool my-tool --payload-file payload.json
+```
+
+| `--draft <id>` / `--tool <id>` | Draft ID or saved tool ID |
+| `--payload <json>` / `--payload-file <path>` | Payload |
+| `--include-step-results` | Include raw step results |
+| `--include-config` | Include full tool config |
+
+**`sg tool edit`** — Apply JSON Patch (RFC 6902) operations.
+
+```bash
+sg tool edit --draft <draftId> --patches '[{"op":"replace","path":"/steps/0/config/url","value":"..."}]'
+sg tool edit --tool my-tool --patches patches.json --test --payload '{...}'
+```
+
+| `--patches <json-or-file>` | JSON Patch array (inline or file) |
+| `--test` | Run patched tool after accepting |
+
+**`sg tool save`** — Persist draft to database. Deletes draft file on success.
+
+```bash
+sg tool save --draft <draftId>
+```
+
+**`sg tool list` / `sg tool find`**
+
+```bash
+sg tool list                    # all non-archived tools
+sg tool find "shopify orders"   # search (compact results)
+sg tool find --id my-tool       # exact ID lookup (full config)
+```
+
+### System Commands
+
+**`sg system create`**
+
+```bash
+sg system create --id slack --template slack --sensitive-credentials client_secret
+sg system create --id my_api --url https://api.example.com --credentials '{"api_key":"..."}' --sensitive-credentials api_key
+```
+
+| `--id <id>` | System ID (lowercase, underscores only) |
+| `--url <url>` | API base URL |
+| `--template <id>` | Template ID (stripe, shopify, slack, etc.) |
+| `--credentials <json>` | Non-sensitive credentials |
+| `--sensitive-credentials <fields>` | Comma-separated fields to prompt for securely |
+| `--docs-url <url>` | Documentation URL to scrape |
+| `--env <environment>` | Environment: `dev` or `prod` (default: prod) |
+
+**`sg system edit`** — Update system config or credentials. Supports `--env dev|prod`.
+**`sg system list` / `sg system find`** — List or search systems. `find` supports `--env dev|prod`.
+
+**`sg system call`** — **CRITICAL for tool building.** Make authenticated calls to APIs, databases, and file servers. Use this to:
+
+- Test system authentication works
+- Explore API endpoints and response structures
+- Verify field names and data shapes BEFORE building tools
+- Debug failing tools by testing individual endpoints
+
+```bash
+# Include auth header with credential placeholder
+sg system call --url https://api.example.com/users \
+  --system-id my_api \
+  --headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
+
+# POST request with auth and body
+sg system call --url https://api.example.com/users \
+  --system-id my_api \
+  --method POST \
+  --headers '{"Authorization":"Bearer <<my_api_access_token>>"}' \
+  --body '{"name":"test"}'
+
+# Database query (Postgres)
+sg system call --url "postgres://<<my_db_host>>:5432/mydb" \
+  --system-id my_db \
+  --body '{"query":"SELECT * FROM users LIMIT 5"}'
+
+# File server (SFTP)
+sg system call --url "sftp://<<my_sftp_host>>:22/data" \
+  --system-id my_sftp \
+  --body '{"operation":"list","path":"/"}'
+```
+
+| Flag                | Description                                               |
+| ------------------- | --------------------------------------------------------- |
+| `--url <url>`       | Full URL with protocol (http/https/postgres/sftp/ftp/smb) |
+| `--system-id <id>`  | System ID for credential injection                        |
+| `--method <method>` | HTTP method (GET, POST, PUT, DELETE, PATCH)               |
+| `--headers <json>`  | HTTP headers JSON with credential placeholders            |
+| `--body <string>`   | Request body (JSON string)                                |
+| `--env <env>`       | Environment: `dev` or `prod`                              |
+| `--file <key=path>` | File references (repeatable)                              |
+
+**`sg system search-docs`** — Search system documentation.
+
+```bash
+sg system search-docs --system-id slack -k "send message channels"
+```
+
+**`sg system oauth`** — Authenticate via OAuth.
+
+```bash
+sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.readonly"
+sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"
+```
+
+| `--system-id <id>` | Required |
+| `--scopes <scopes>` | Space-separated OAuth scopes (required) |
+| `--grant-type <type>` | `authorization_code` (default) or `client_credentials` |
+
+### Run Commands
+
+**`sg run list`** — List execution runs. Filter by `--tool`, `--status`, `--source`, `--limit`.
+**`sg run get <runId>`** — Get run details. `--fetch-results` to include data.
+
+---
+
+## Tool Configuration — Full Schema
+
+```json
+{
+  "id": "kebab-case-tool-name",
+  "instruction": "Brief human-readable description of what this tool does",
+  "steps": [
+    {
+      "id": "unique-step-id",
+      "config": {
+        "systemId": "example_system",
+        "url": "https://api.example.com/endpoint?param=<<payload_field>>",
+        "method": "GET",
+        "headers": {
+          "Authorization": "Bearer <<example_system_access_token>>"
+        },
+        "queryParams": { "limit": "10" },
+        "body": "{ \"key\": \"<<payload_field>>\" }"
+      },
+      "dataSelector": "(sourceData) => sourceData.previousStep.data.items",
+      "transformCode": "(items) => items.map(i => ({ id: i.id, name: i.name }))",
+      "failureBehavior": "abort"
+    }
+  ],
+  "outputTransform": "(sourceData) => sourceData.stepId.data",
+  "outputSchema": { "type": "object", "properties": {} },
+  "inputSchema": { "type": "object", "properties": {} }
+}
+```
+
+### Step Config Fields
+
+| Field         | Type   | Description                                  |
+| ------------- | ------ | -------------------------------------------- |
+| `systemId`    | string | System whose credentials to use              |
+| `url`         | string | Full URL with `<<variable>>` placeholders    |
+| `method`      | string | HTTP method                                  |
+| `headers`     | object | HTTP headers with credential placeholders    |
+| `queryParams` | object | URL query parameters                         |
+| `body`        | string | Request body (JSON string with placeholders) |
+| `pagination`  | object | Auto-pagination config (see below)           |
+
+### Step Behavior Fields
+
+| Field             | Type   | Description                                      |
+| ----------------- | ------ | ------------------------------------------------ |
+| `dataSelector`    | string | JS function controlling step input and loop mode |
+| `transformCode`   | string | JS function to transform the step's response     |
+| `failureBehavior` | string | `abort` (default), `continue`, or `skip`         |
+
+---
+
+## Credential Placeholders
+
+System credentials are namespaced as `<<systemId_credentialKey>>` and resolved server-side at execution time. **You MUST explicitly reference them in headers.**
+
+### Auth Header Patterns
+
+```json
+{"Authorization": "Bearer <<stripe_api_key>>"}
+{"Authorization": "Bearer <<gmail_access_token>>"}
+{"X-API-Key": "<<my_api_api_key>>"}
+{"Authorization": "Basic <<(sourceData) => Buffer.from(sourceData.my_api_username + ':' + sourceData.my_api_password).toString('base64')>>"}
+```
+
+### Credential Lifecycle
+
+- Non-sensitive creds (`client_id`, `auth_url`, etc.) are stored via `--credentials`
+- Sensitive creds (`api_key`, `client_secret`) use `--sensitive-credentials` for secure input
+- OAuth tokens (`access_token`, `refresh_token`) are auto-refreshed before each step execution
+- Placeholders like `<<gmail_access_token>>` always resolve to the current (refreshed) token
+
+---
+
+## Variables and Data Flow
+
+### Variable Syntax
+
+All step config fields support `<<variable>>` placeholders:
+
+| Syntax                     | Resolves to                 |
+| -------------------------- | --------------------------- |
+| `<<fieldName>>`            | Payload field or credential |
+| `<<systemId_credKey>>`     | System credential           |
+| `<<stepId.data.field>>`    | Previous step result        |
+| `<<(sourceData) => expr>>` | JavaScript expression       |
+
+**CRITICAL**: Simple `<<varName>>` only works for **top-level keys**. No dots, no nesting.
+
+- VALID: `<<userId>>`, `<<currentItem>>`, `<<stripe_api_key>>`
+- INVALID: `<<currentItem.id>>`, `<<sourceData.userId>>` — these FAIL at runtime
+
+For nested access, use arrow functions: `<<(sourceData) => sourceData.currentItem.id>>`
+
+### sourceData Object
+
+`sourceData` is the cumulative state available to all JS expressions (data selectors, transforms, variable expressions):
+
+```javascript
+sourceData = {
+  // Payload fields at ROOT level (NEVER use sourceData.payload.*)
+  userId: "123",
+  date: "2024-01-15",
+
+  // Previous step results, keyed by step ID
+  // Object-selector step:
+  getUsers: { currentItem: {}, data: { users: [...] }, success: true },
+  // Array-selector (loop) step:
+  fetchDetails: [
+    { currentItem: "id1", data: { name: "Alice" }, success: true },
+    { currentItem: "id2", data: { name: "Bob" }, success: true },
+  ],
+
+  // Current loop item (only set inside a looping step's config)
+  currentItem: { id: 1 },
+
+  // Credentials (flattened, namespaced)
+  systemId_access_token: "...",
+  systemId_api_key: "..."
+}
+```
+
+### Step Result Envelope
+
+**Every** step result is wrapped in an envelope — you MUST account for this.
+
+**Object selector (or no selector)** — step runs once:
+
+```javascript
+sourceData.stepId = { currentItem: <selectorOutput>, data: <apiResponse>, success: true }
+// Access the API response:
+sourceData.stepId.data
+sourceData.stepId.data.users
+```
+
+**Array selector** — step loops, result is an array of envelopes:
+
+```javascript
+sourceData.stepId = [
+  { currentItem: <item1>, data: <response1>, success: true },
+  { currentItem: <item2>, data: <response2>, success: true },
+  ...
+]
+// Access all responses:
+sourceData.stepId.map(item => item.data)
+// Nested arrays:
+sourceData.stepId.flatMap(item => item.data.results)
+// Only successes:
+sourceData.stepId.filter(item => item.success).map(i => i.data)
+```
+
+**NEVER** access step results without `.data` — `sourceData.stepId.results` hits the envelope, not the API response. Use `sourceData.stepId.data.results`.
+
+### Data Selectors
+
+Control what a step receives as input and whether it loops:
+
+| Return type        | Behavior                            |
+| ------------------ | ----------------------------------- |
+| Single object      | Step runs once with that object     |
+| Array              | Step runs once per item (loop mode) |
+| `undefined`/`null` | Step receives full sourceData       |
+
+In loop mode, `sourceData.currentItem` is set to the current array element.
+
+Empty arrays are valid — the step simply skips execution.
+
+### Step Result References (in `<<>>` placeholders)
+
+```
+<<stepId.data>>              — full response data (object-selector step)
+<<stepId.data.field>>        — nested field
+<<stepId.data.items[0].id>>  — array element
+```
+
+### Execution Pipeline
+
+For each step in order:
+
+1. Build `sourceData`: `{ ...originalPayload, ...previousStepResults, ...credentials }`
+2. Run `dataSelector(sourceData)` → determines single vs loop execution
+3. For each item: merge `currentItem` into `sourceData`, resolve `<<>>` variables, execute step
+4. `transformCode` runs on the raw response → output becomes `.data` in the envelope
+5. Wrap result: `{ currentItem, data, success }` and store in `sourceData[stepId]`
+6. After all steps: run `outputTransform(sourceData)` to shape final output
+
+### Complete Example: List-then-Detail Pattern
+
+A tool that lists Gmail message IDs, then fetches details for each:
+
+```json
+{
+  "id": "get-recent-emails",
+  "instruction": "Fetches the 10 most recent Gmail emails with subject, sender, and snippet",
+  "steps": [
+    {
+      "id": "list-messages",
+      "config": {
+        "systemId": "gmail",
+        "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10",
+        "method": "GET",
+        "headers": { "Authorization": "Bearer <<gmail_access_token>>" }
+      }
+    },
+    {
+      "id": "get-details",
+      "dataSelector": "(sourceData) => sourceData[\"list-messages\"].data.messages.map(m => m.id)",
+      "config": {
+        "systemId": "gmail",
+        "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages/<<currentItem>>?format=metadata&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date",
+        "method": "GET",
+        "headers": { "Authorization": "Bearer <<gmail_access_token>>" }
+      }
+    }
+  ],
+  "outputTransform": "(sourceData) => sourceData[\"get-details\"].map(item => { var h = item.data.payload.headers; var get = function(n) { var f = h.find(function(x) { return x.name === n; }); return f ? f.value : null; }; return { id: item.data.id, subject: get(\"Subject\"), from: get(\"From\"), date: get(\"Date\"), snippet: item.data.snippet }; })"
+}
+```
+
+What happens at runtime:
+
+1. **list-messages** runs once (no dataSelector) → `sourceData["list-messages"] = { currentItem: {}, data: { messages: [{id: "abc"}, {id: "def"}, ...] }, success: true }`
+2. **get-details** dataSelector returns `["abc", "def", ...]` (an array) → step loops over each ID
+3. Each loop iteration sets `currentItem` to the string ID, which `<<currentItem>>` injects into the URL
+4. Loop results stored as: `sourceData["get-details"] = [{ currentItem: "abc", data: {id, snippet, payload...}, success }, ...]`
+5. **outputTransform** maps over the array of envelopes, extracting `.data` fields from each
+
+---
+
+## HTTP API Patterns
+
+### Pagination
+
+```json
+{
+  "pagination": {
+    "type": "offset|cursor|page",
+    "pageSize": 100,
+    "cursorPath": "$.nextPageToken",
+    "stopCondition": "(response) => !response.hasMore"
+  }
+}
+```
+
+| Type     | How it works                                                 |
+| -------- | ------------------------------------------------------------ |
+| `offset` | Increments `offset` param by `pageSize` each page            |
+| `cursor` | Extracts next cursor from `cursorPath`, sends as query param |
+| `page`   | Increments `page` query param                                |
+
+All types stop when `stopCondition` returns true, response is empty, or max pages reached.
+
+### Common Auth Patterns by Service Type
+
+| Service                      | Header                                                |
+| ---------------------------- | ----------------------------------------------------- |
+| OAuth (Google, GitHub, etc.) | `"Authorization": "Bearer <<systemId_access_token>>"` |
+| API Key (Stripe, etc.)       | `"Authorization": "Bearer <<systemId_api_key>>"`      |
+| API Key in header            | `"X-API-Key": "<<systemId_api_key>>"`                 |
+
+---
+
+## Systems
+
+### Credential Model
+
+- `credentials` — non-sensitive config stored directly (client_id, auth_url, scopes, etc.)
+- `sensitiveCredentials` — secrets requiring secure UI input (api_key, client_secret)
+- **NEVER ask users to paste secrets in chat** — always use `--sensitive-credentials`
+
+### Templates
+
+Templates auto-populate endpoints and OAuth config. Use `sg system find` to discover available templates.
+
+**Preconfigured OAuth** (no user client_id/secret needed): slack, salesforce, asana, notion, airtable, jira, confluence
+
+### OAuth Flow
+
+1. `sg system create --id gmail --url https://gmail.googleapis.com --credentials '{"auth_url":"...","token_url":"..."}' --sensitive-credentials client_id,client_secret`
+2. `sg system oauth --system-id gmail --scopes "..."`
+3. User authenticates in browser → tokens saved automatically
+
+### System IDs
+
+- Lowercase letters, numbers, underscores only — **no hyphens**
+- Used for credential namespacing: `<<systemId_credKey>>`
+
+---
+
+## Debugging Failed Tools
+
+### Common Errors and Fixes
+
+| Error                 | Cause                              | Fix                                                                       |
+| --------------------- | ---------------------------------- | ------------------------------------------------------------------------- |
+| 401 Unauthorized      | Missing or invalid auth header     | Add `"Authorization": "Bearer <<systemId_access_token>>"` to step headers |
+| 403 Forbidden         | Wrong scopes or permissions        | Check OAuth scopes, re-authenticate                                       |
+| Empty `data: {}`      | No outputTransform or dataSelector | Add `outputTransform` to extract from step results                        |
+| Variable not resolved | Wrong placeholder syntax           | Check `<<systemId_credKey>>` matches actual credential keys               |
+| Step references empty | Wrong step ID in reference         | Verify `<<stepId.data.field>>` matches actual step IDs                    |
+
+### Debug Workflow
+
+1. Run with `--include-step-results` to see raw step responses
+2. Check each step's `data` field — is the API returning what you expect?
+3. Verify credential placeholders match `sg system find --id <systemId>` placeholder list
+4. **Test API calls directly with `sg system call`** — isolate whether the issue is auth, endpoint, or transform:
+   ```bash
+   # Test the exact URL from your failing step
+   sg system call --url "https://api.example.com/endpoint" \
+     --system-id my_api \
+     --headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
+   ```
+5. Compare `sg system call` response to what your tool expects — fix transforms accordingly
+
+### Self-Healing Pattern
+
+When an outputTransform or dataSelector fails, the executor retries with an LLM-generated fix. To help this:
+
+- Throw descriptive errors: `throw new Error("Expected array at data.items, got: " + typeof data.items)`
+- Check for null/undefined with `?.` and defaults
+- Validate arrays with `Array.isArray()` before calling array methods
+
+---
+
+## Workflow Guide
+
+### Pre-Building: Test with `sg system call`
+
+**ALWAYS test endpoints with `sg system call` before building tools.** This is the most important step to avoid broken tools.
+
+1. **Verify authentication** — Test that credentials work:
+
+   ```bash
+   sg system call --url "https://api.example.com/me" \
+     --system-id my_api \
+     --headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
+   ```
+
+2. **Explore response structure** — Understand what the API returns:
+
+   ```bash
+   sg system call --url "https://api.example.com/users?limit=2" \
+     --system-id my_api \
+     --headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
+   ```
+
+   Look at the response to understand:
+   - Where is the data array? (`data.users`, `data.items`, `data.results`?)
+   - What fields are available? (exact field names matter!)
+   - Is there pagination info? (`nextCursor`, `hasMore`, `total`?)
+
+3. **Test the exact endpoints your tool will use** — Don't guess:
+   ```bash
+   # If your tool will fetch user details by ID:
+   sg system call --url "https://api.example.com/users/123" \
+     --system-id my_api \
+     --headers '{"Authorization":"Bearer <<my_api_access_token>>"}'
+   ```
+
+### Full Workflow
+
+1. **Create system** → `sg system create --id my_api --url ... --sensitive-credentials api_key`
+2. **Authenticate** → `sg system oauth` (if OAuth) or credentials are already set
+3. **Test auth** → `sg system call` to verify credentials work
+4. **Explore API** → `sg system search-docs` + more `sg system call` to test endpoints
+5. **Build tool** → Construct full config JSON, `sg tool build --config '...'`
+6. **Test** → `sg tool run --draft <id> --include-step-results`
+7. **Iterate** → `sg tool edit --draft <id> --patches '[...]' --test`
+8. **Save** → `sg tool save --draft <id>`
+
+---
+
+## Deploying Tools to Production
+
+After building and saving a tool, integrate it into your application:
+
+### REST API (Any Language)
+
+```bash
+# Run a tool
+curl -X POST "https://api.superglue.cloud/v1/tools/{toolId}/run" \
+  -H "Authorization: Bearer $SUPERGLUE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"inputs": {"userId": "123"}}'
+
+# Webhook trigger (async, fire-and-forget)
+curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"userId": "123"}'
+```
+
+### TypeScript SDK
+
+```typescript
+import { configure, runTool } from "@superglue/client";
+configure({ apiKey: process.env.SUPERGLUE_API_KEY });
+const { data } = await runTool("my-tool-id", { inputs: { userId: "123" } });
+```
+
+### Python SDK
+
+```python
+import os
+from superglue_client import SuperglueClient
+from superglue_client.api.tools import run_tool
+client = SuperglueClient(base_url="https://api.superglue.cloud/v1", token=os.environ["SUPERGLUE_API_KEY"])
+result = run_tool.sync(client=client, tool_id="my-tool-id", body={"inputs": {"userId": "123"}})
+```
+
+**For complete integration patterns** (error handling, retries, webhooks, async execution), read `references/integration.md`.
+
+---
+
+## Reference Files
+
+For detailed documentation on specific topics, read these files in the `references/` directory:
+
+| File                                  | When to read                                                                                     |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `references/integration.md`           | **READ THIS** when deploying tools to production - SDK usage, REST API, webhooks, error handling |
+| `references/databases.md`             | Building tools that query PostgreSQL/MySQL databases                                             |
+| `references/file-servers.md`          | Building tools that interact with FTP/SFTP/SMB file servers                                      |
+| `references/transforms-and-output.md` | Complex data transformations, output shaping, JS sandbox constraints                             |
+
+**Important:** When the user asks about integrating superglue into their codebase, deploying tools, using the SDK, or calling tools from code, you MUST read `references/integration.md` for complete examples.
+
+---
+
+## Draft Management
+
+Drafts live in `.superglue/drafts/<draftId>.json`. Created by `build`, updated by `edit`, deleted by `save`. Ephemeral — not persisted across sessions.
+
+## File References
+
+Attach files with `--file key=path`. Reference in payloads with `file::<key>`. Auto-parsed via `/v1/extract`.
+
+```bash
+sg tool run --draft <id> --payload '{"data": "file::mysheet"}' --file mysheet=data.xlsx
+```
+
+## Configuration
+
+Created by `sg init` at `.superglue/config.json` (project-local) or `~/.superglue/config.json` (global):
+
+```json
+{
+  "apiKey": "...",
+  "endpoint": "https://api.superglue.cloud",
+  "webEndpoint": "https://app.superglue.cloud",
+  "output": { "mode": "stdout", "directory": ".superglue/output" }
+}
+```
+
+Config file is optional if `SUPERGLUE_API_KEY` and `SUPERGLUE_API_ENDPOINT` env vars are set. See **Installation & Setup** above.