@superglue/cli 1.1.34 → 1.1.35

package/dist/skills/superglue/SKILL.md

@@ -218,7 +218,7 @@ Agents familiar with the web tool names can map them directly to CLI commands:
 | `save_tool`                                      | `sg tool save --draft <draftId>`               | Persists a draft to the database                                   |
 | `run_command` with `vfs` for `/org/tools/`       | `sg tool find --id <id>` / `sg tool find <q>`  | Full config with `--id`, compact search with a query string        |
 | `create_system`                                  | `sg system create --name "..." --url "..."`    | Use `--template <id>` when available                               |
-| `edit_system`                                    | `sg system edit --id <id> ...`                 | Supports `--env dev\|prod`                                         |
+| `edit_system`                                    | `sg system edit --id <id> ...`                 | Edits the system with that exact ID                                |
 | `run_command` with `vfs` for `/org/systems/`     | `sg system find <query>` / `--id <id>`         | Returns secret-key presence and the system URL                     |
 | Credentials VFS / saved credentials              | `sg system credentials get/set/clear`          | Manage the current user's credentials for a system                 |
 | `call_system`                                    | `sg system call --url "..." --system-id <id>`  | Authenticated ad-hoc calls for testing / schema introspection      |
@@ -267,7 +267,7 @@ sg system create --name "Slack" --template slack
 sg system edit --id my_api --credentials '{...}'
 sg system list
 sg system find slack
-sg system find --id my_api --env dev
+sg system find --id my_api
 sg system credentials get --system-id my_api
 sg system credentials set --system-id my_api --credentials '{"api_key":"sk-xxx"}'
 sg system credentials clear --system-id my_api
@@ -414,17 +414,38 @@ sourceData = {
   // Current loop item (only set inside a looping step's config)
   currentItem: { id: 1 },
 
+  // Persistent per-tool state (see Persistent Tool State)
+  persistedState: { lastSyncedAt: "..." },
+
   // Credentials (flattened, namespaced)
   my_api_access_token: "...",
   my_api_api_key: "..."
 }
 ```
 
+### Persistent Tool State
+
+`sourceData.persistedState` is a per-tool key-value object that persists across runs of a saved tool. It is loaded before the run starts and written back only after the workflow and run record complete successfully. A failed step that stops execution, failed output processing, cancellation, or run-finalization failure leaves the previous state unchanged. A step with `failureBehavior: "continue"` does not fail the run, so earlier state changes can still commit when the remaining workflow succeeds.
+
+- Write it by setting keys inside a transform: `(sourceData) => { sourceData.persistedState.cursor = sourceData.fetchOrders.data.nextCursor; return sourceData.fetchOrders.data.items; }`. Never reassign `sourceData.persistedState` itself — whether reassignment takes effect depends on the execution context, so only key mutation is reliable.
+- Read it anywhere: `<<(sourceData) => sourceData.persistedState.lastSyncedAt || "2024-01-01">>`. A tool's first run starts with `{}`, so every read needs a fallback.
+- Inline runs (`sg tool run` with an unsaved config) start with empty state and do not persist it; only saved-tool runs (frontend, agent, REST, MCP, webhook, schedule, tool-chain) persist state.
+- Limits: 100 keys, 64KB per value. Exceeding a limit rejects the entire state write and records a run warning — the run itself still succeeds.
+- Concurrent runs of the same tool are reconciled per key with compare-and-set: if another run changed a key first, this run's value for that key is discarded and a run warning is recorded.
+- Batch continuation: process a large import in manageable batches and save the next cursor, so each scheduled run continues where the previous run stopped.
+- Polling-based change detection: poll an API on a schedule, compare its version or fingerprint with the previous result, and trigger follow-up work only when it changes. This is useful when the provider lacks the required webhook.
+- Incremental syncs and dedupe: store a timestamp or cursor for new records, or a bounded set such as `persistedState.seenIds`.
+- State gives at-least-once execution with progress tracking, never exactly-once: crashes, concurrent-run conflicts, and state resets all cause re-processing, which re-executes side effects. Steps that write to external systems MUST be replay-safe — upsert by a stable external id or pass an idempotency key — or duplicates will land in the target system.
+- Keep set-valued keys bounded (e.g. keep only the most recent ~1,000 ids): an unbounded set eventually exceeds the 64KB value limit, which rejects the tool's entire state write on every run.
+- Never copy credential values into state — state is stored unencrypted and readable by anyone with read access to the tool.
+- Inspect current state via `sg tool state get <toolId>` (values matching known system credentials are masked); reset it via `sg tool state reset <toolId>`. A reset wins over in-flight runs: their updates to pre-reset keys are discarded as conflicts; only keys they newly add are kept.
+- Set state deliberately via `sg tool state set <toolId> --state '<json>'` (or `--state-file`) — a full replace, subject to the same key and size limits. To test warm-state behavior without touching real state, pass `--state-fixture '<json>'` (or `--state-fixture-file`) to `sg tool run`: it seeds `sourceData.persistedState` for that run and the run never saves state changes. Side effects still execute, including `tool:` chain webhooks — a chained tool runs for real against its own real state.
+
 ### Naming Rules — Avoiding Key Collisions
 
 Everything in `sourceData` shares ONE flat namespace. Saving a tool rejects payload input keys and step ids that collide with it:
 
-- `__files__`, `currentItem`, `sg_auth_email`, `sg_auth_jwt` — injected by the runtime
+- `__files__`, `currentItem`, `persistedState`, `sg_auth_email`, `sg_auth_jwt` — injected by the runtime
 - `page`, `offset`, `cursor`, `limit`, `pageSize` — rejected only when the tool has a paginated step, because they would shadow the live pagination counters; on non-paginated tools they are allowed but discouraged (a later edit that adds pagination will force a rename)
 - the tool's own step ids — the step result overwrites a same-named payload key
 - anything starting with `<systemId>_` for a system the tool uses — the entire prefix is reserved for namespaced credentials (`<systemId>_<credKey>`, `<systemId>_url`), even names that don't match an existing credential, because credentials added to the system later would silently shadow the input
@@ -510,12 +531,14 @@ System id="stripe", selected credential has secret named: api_key
 
 Basic auth auto-encodes: if the value after `Basic ` isn't already base64, the engine encodes it.
 
-**System URL variables** — use these instead of hardcoding base URLs. They switch automatically between dev/prod environments:
+**System URL variables** — use these instead of hardcoding base URLs. They resolve the URL of the exact referenced system ID:
 
 ```json
 { "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
 ```
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Set an override with `sg system credentials set --system-id <id> --credentials '{...}' --url <url>` when each tenant has its own host; pass an empty string to clear it.
+
 **Credential lifecycle:**
 
 - Pass all secret values via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
@@ -538,7 +561,7 @@ sg system create --name "My API" --url https://api.example.com \
   --credentials '{"client_id":"...","client_secret":"...","auth_url":"https://example.com/oauth/authorize","token_url":"https://example.com/oauth/token"}'
 ```
 
-**Dev/Prod environments:** `--env dev|prod` at creation (immutable afterward). Two systems with the same ID but different environments are automatically linked. Dev systems inherit documentation from their linked prod system. When creating a dev system, always ask for new credentials — never copy from prod.
+**Tags:** do not add tags by default. Add tags only when the user explicitly requests them or when existing systems show a clear tag or grouping convention that applies. Reuse exact existing tag values; do not invent new tags. Tags are metadata only. Tools and credentials always reference the exact system ID.
 
 **System-specific instructions:** systems may include `specificInstructions` from the user (visible in `sg system find` output). Follow them when present — they override general patterns.
 
@@ -615,7 +638,7 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 - **`<<currentItem.id>>`** — must use arrow function syntax: `<<(sourceData) => sourceData.currentItem.id>>`
 - **Hardcoded pagination params** — use `<<page>>`, `<<offset>>`, `<<cursor>>`, `<<limit>>`
 - **Missing auth headers** — credentials are never automatically included in any protocol, including for OAuth systems (only token refresh is automatic)
-- **Hardcoded base URLs** — prefer system URL variables (`<<systemId_url>>`) for environment portability
+- **Hardcoded base URLs** — prefer system URL variables (`<<systemId_url>>`) so tools follow the referenced system's configured URL
 - **Empty `instruction`** — never leave the tool-level `instruction` blank
 - **Adding `outputSchema` unsolicited** — only add when the user explicitly requests a specific response structure
 - **Multi-line `outputTransform`** — must be a single-line JS string (no literal newlines or tabs)

package/dist/skills/superglue/references/file-handling.md

@@ -207,7 +207,7 @@ To make files downloadable from the tool's API response, set `outputFile: true`
       "config": { "type": "request", "url": "https://api.example.com/report" }
     },
     {
-      "id": "generateReport",
+      "id": "createCsv",
       "config": {
         "type": "transform",
         "transformCode": "(sourceData) => ({ __files__: { \"report.csv\": Papa.unparse(sourceData.fetchData.data) } })"

package/dist/skills/superglue/references/http.md

@@ -164,7 +164,7 @@ XML responses are parsed into a JSON tree with ALL tag names normalized to UPPER
 
 Non-2xx responses throw with method, URL, response body preview (1000 chars), masked config, and retry count. Any response with status in the 2xx range is treated as success and returned to the step as-is — the runtime does not scan successful response bodies for error fields, so APIs that return HTTP 200 with `{ "error": "..." }` must be handled by your transform or by setting a `stopCondition`/assertion at the step level.
 
-Bypass: set `failureBehavior: "continue"` to skip the non-2xx throw and return the response anyway.
+Set step-level `failureBehavior: "continue"` to keep the workflow running after a non-2xx failure. The failure remains in `stepResults`.
 
 ### Retry Behavior
 
@@ -249,7 +249,7 @@ When an HTTP step downloads a file (PDF, CSV, binary response), set `outputFile:
 ## Common Pitfalls
 
 - Hardcoding base URLs instead of using `<<systemId_url>>`.
-- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the system's `url` exactly as stored, which may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
+- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the selected credential's `url` override when set, else the system's `url`, exactly as stored — it may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
 - Forgetting auth headers entirely — nothing is injected automatically, including for OAuth systems (only token refresh is automatic)
 - Forgetting `outputFile: true` on steps that download files the user wants
 - Putting pagination variables in the config but not setting a `pagination` block, or vice versa

package/dist/skills/superglue/references/mongodb.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
 
 ### Fields

package/dist/skills/superglue/references/mssql.md

@@ -15,6 +15,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields
@@ -224,7 +226,7 @@ Defaults are tuned for Azure SQL; on-prem servers usually need adjustments:
 - **Self-signed certificates** — on-prem servers rarely have CA-signed certs, so the default `trustServerCertificate=false` fails the TLS handshake. Add `?trustServerCertificate=true` (keeps encryption, skips CA validation).
 - **Old SQL Server versions** — SQL Server 2008/2008 R2 without TLS 1.2 patches cannot complete a modern TLS handshake. Use `?encrypt=false` as a last resort, preferably only over the Secure Gateway tunnel.
 - **Named instances** — use the `?instanceName=` query parameter (see URL Format above); remember SQL Browser (UDP 1434) is required for instance resolution and does not work through the Secure Gateway tunnel.
-- **Firewalled servers** — on-prem databases are typically not internet-reachable; configure the system with a Secure Gateway tunnel.
+- **Firewalled servers** — on-prem databases are typically not internet-reachable; configure the system with a Secure Gateway tunnel. Direct users to the setup guide at https://superglue.ai/docs/guides/secure-gateway/ — do not describe the setup flow from memory.
 
 ### Retry Behavior
 

package/dist/skills/superglue/references/odbc.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields

package/dist/skills/superglue/references/postgres.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields

package/dist/skills/superglue/references/redis.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
 
 ### Fields

package/dist/skills/superglue/references/sftp-smb.md

@@ -15,6 +15,8 @@ FTP, SFTP, and SMB share an identical operation interface. Only the URL protocol
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for file server steps.
 
 ### Fields

package/dist/skills/superglue/references/superglue-info.md

@@ -69,7 +69,6 @@ The persistent left sidebar contains these top-level items:
 - **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
 - **Control Panel** (`/admin`) — expandable group for organization and account administration:
   - **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
-  - **Landscape** (`/landscape`) — graph overview of tools, systems, and their connections.
   - **Schedules** (`/admin?view=schedules`) — scheduled and recurring tool runs.
   - **Access Rules** (`/admin/access`) — role and access-rule configuration; visible to admins on paid tiers. Use the access-rules reference for RBAC behavior, base roles, and personal roles.
   - **Organization** (`/organization`) — visible on paid tiers as a standalone page without tabs. It shows members, invitations, role assignment, and member-management actions; management actions are admin-gated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superglue/cli",
-  "version": "1.1.34",
+  "version": "1.1.35",
   "bin": {
     "sg": "./dist/cli.js"
   },
@@ -15,7 +15,7 @@
     "fast-json-patch": "3.1.1"
   },
   "devDependencies": {
-    "@superglue/shared": "file:./_shared",
+    "@superglue/shared": "file:../shared",
     "@types/node": "25.5.0",
     "tsup": "8.5.1",
     "typescript": "5.8.3"

package/skills/superglue/SKILL.md

@@ -218,7 +218,7 @@ Agents familiar with the web tool names can map them directly to CLI commands:
 | `save_tool`                                      | `sg tool save --draft <draftId>`               | Persists a draft to the database                                   |
 | `run_command` with `vfs` for `/org/tools/`       | `sg tool find --id <id>` / `sg tool find <q>`  | Full config with `--id`, compact search with a query string        |
 | `create_system`                                  | `sg system create --name "..." --url "..."`    | Use `--template <id>` when available                               |
-| `edit_system`                                    | `sg system edit --id <id> ...`                 | Supports `--env dev\|prod`                                         |
+| `edit_system`                                    | `sg system edit --id <id> ...`                 | Edits the system with that exact ID                                |
 | `run_command` with `vfs` for `/org/systems/`     | `sg system find <query>` / `--id <id>`         | Returns secret-key presence and the system URL                     |
 | Credentials VFS / saved credentials              | `sg system credentials get/set/clear`          | Manage the current user's credentials for a system                 |
 | `call_system`                                    | `sg system call --url "..." --system-id <id>`  | Authenticated ad-hoc calls for testing / schema introspection      |
@@ -267,7 +267,7 @@ sg system create --name "Slack" --template slack
 sg system edit --id my_api --credentials '{...}'
 sg system list
 sg system find slack
-sg system find --id my_api --env dev
+sg system find --id my_api
 sg system credentials get --system-id my_api
 sg system credentials set --system-id my_api --credentials '{"api_key":"sk-xxx"}'
 sg system credentials clear --system-id my_api
@@ -414,17 +414,38 @@ sourceData = {
   // Current loop item (only set inside a looping step's config)
   currentItem: { id: 1 },
 
+  // Persistent per-tool state (see Persistent Tool State)
+  persistedState: { lastSyncedAt: "..." },
+
   // Credentials (flattened, namespaced)
   my_api_access_token: "...",
   my_api_api_key: "..."
 }
 ```
 
+### Persistent Tool State
+
+`sourceData.persistedState` is a per-tool key-value object that persists across runs of a saved tool. It is loaded before the run starts and written back only after the workflow and run record complete successfully. A failed step that stops execution, failed output processing, cancellation, or run-finalization failure leaves the previous state unchanged. A step with `failureBehavior: "continue"` does not fail the run, so earlier state changes can still commit when the remaining workflow succeeds.
+
+- Write it by setting keys inside a transform: `(sourceData) => { sourceData.persistedState.cursor = sourceData.fetchOrders.data.nextCursor; return sourceData.fetchOrders.data.items; }`. Never reassign `sourceData.persistedState` itself — whether reassignment takes effect depends on the execution context, so only key mutation is reliable.
+- Read it anywhere: `<<(sourceData) => sourceData.persistedState.lastSyncedAt || "2024-01-01">>`. A tool's first run starts with `{}`, so every read needs a fallback.
+- Inline runs (`sg tool run` with an unsaved config) start with empty state and do not persist it; only saved-tool runs (frontend, agent, REST, MCP, webhook, schedule, tool-chain) persist state.
+- Limits: 100 keys, 64KB per value. Exceeding a limit rejects the entire state write and records a run warning — the run itself still succeeds.
+- Concurrent runs of the same tool are reconciled per key with compare-and-set: if another run changed a key first, this run's value for that key is discarded and a run warning is recorded.
+- Batch continuation: process a large import in manageable batches and save the next cursor, so each scheduled run continues where the previous run stopped.
+- Polling-based change detection: poll an API on a schedule, compare its version or fingerprint with the previous result, and trigger follow-up work only when it changes. This is useful when the provider lacks the required webhook.
+- Incremental syncs and dedupe: store a timestamp or cursor for new records, or a bounded set such as `persistedState.seenIds`.
+- State gives at-least-once execution with progress tracking, never exactly-once: crashes, concurrent-run conflicts, and state resets all cause re-processing, which re-executes side effects. Steps that write to external systems MUST be replay-safe — upsert by a stable external id or pass an idempotency key — or duplicates will land in the target system.
+- Keep set-valued keys bounded (e.g. keep only the most recent ~1,000 ids): an unbounded set eventually exceeds the 64KB value limit, which rejects the tool's entire state write on every run.
+- Never copy credential values into state — state is stored unencrypted and readable by anyone with read access to the tool.
+- Inspect current state via `sg tool state get <toolId>` (values matching known system credentials are masked); reset it via `sg tool state reset <toolId>`. A reset wins over in-flight runs: their updates to pre-reset keys are discarded as conflicts; only keys they newly add are kept.
+- Set state deliberately via `sg tool state set <toolId> --state '<json>'` (or `--state-file`) — a full replace, subject to the same key and size limits. To test warm-state behavior without touching real state, pass `--state-fixture '<json>'` (or `--state-fixture-file`) to `sg tool run`: it seeds `sourceData.persistedState` for that run and the run never saves state changes. Side effects still execute, including `tool:` chain webhooks — a chained tool runs for real against its own real state.
+
 ### Naming Rules — Avoiding Key Collisions
 
 Everything in `sourceData` shares ONE flat namespace. Saving a tool rejects payload input keys and step ids that collide with it:
 
-- `__files__`, `currentItem`, `sg_auth_email`, `sg_auth_jwt` — injected by the runtime
+- `__files__`, `currentItem`, `persistedState`, `sg_auth_email`, `sg_auth_jwt` — injected by the runtime
 - `page`, `offset`, `cursor`, `limit`, `pageSize` — rejected only when the tool has a paginated step, because they would shadow the live pagination counters; on non-paginated tools they are allowed but discouraged (a later edit that adds pagination will force a rename)
 - the tool's own step ids — the step result overwrites a same-named payload key
 - anything starting with `<systemId>_` for a system the tool uses — the entire prefix is reserved for namespaced credentials (`<systemId>_<credKey>`, `<systemId>_url`), even names that don't match an existing credential, because credentials added to the system later would silently shadow the input
@@ -510,12 +531,14 @@ System id="stripe", selected credential has secret named: api_key
 
 Basic auth auto-encodes: if the value after `Basic ` isn't already base64, the engine encodes it.
 
-**System URL variables** — use these instead of hardcoding base URLs. They switch automatically between dev/prod environments:
+**System URL variables** — use these instead of hardcoding base URLs. They resolve the URL of the exact referenced system ID:
 
 ```json
 { "url": "<<salesforce_url>>/services/data/v58.0/sobjects/Account" }
 ```
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Set an override with `sg system credentials set --system-id <id> --credentials '{...}' --url <url>` when each tenant has its own host; pass an empty string to clear it.
+
 **Credential lifecycle:**
 
 - Pass all secret values via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
@@ -538,7 +561,7 @@ sg system create --name "My API" --url https://api.example.com \
   --credentials '{"client_id":"...","client_secret":"...","auth_url":"https://example.com/oauth/authorize","token_url":"https://example.com/oauth/token"}'
 ```
 
-**Dev/Prod environments:** `--env dev|prod` at creation (immutable afterward). Two systems with the same ID but different environments are automatically linked. Dev systems inherit documentation from their linked prod system. When creating a dev system, always ask for new credentials — never copy from prod.
+**Tags:** do not add tags by default. Add tags only when the user explicitly requests them or when existing systems show a clear tag or grouping convention that applies. Reuse exact existing tag values; do not invent new tags. Tags are metadata only. Tools and credentials always reference the exact system ID.
 
 **System-specific instructions:** systems may include `specificInstructions` from the user (visible in `sg system find` output). Follow them when present — they override general patterns.
 
@@ -615,7 +638,7 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 - **`<<currentItem.id>>`** — must use arrow function syntax: `<<(sourceData) => sourceData.currentItem.id>>`
 - **Hardcoded pagination params** — use `<<page>>`, `<<offset>>`, `<<cursor>>`, `<<limit>>`
 - **Missing auth headers** — credentials are never automatically included in any protocol, including for OAuth systems (only token refresh is automatic)
-- **Hardcoded base URLs** — prefer system URL variables (`<<systemId_url>>`) for environment portability
+- **Hardcoded base URLs** — prefer system URL variables (`<<systemId_url>>`) so tools follow the referenced system's configured URL
 - **Empty `instruction`** — never leave the tool-level `instruction` blank
 - **Adding `outputSchema` unsolicited** — only add when the user explicitly requests a specific response structure
 - **Multi-line `outputTransform`** — must be a single-line JS string (no literal newlines or tabs)

package/skills/superglue/references/file-handling.md

@@ -207,7 +207,7 @@ To make files downloadable from the tool's API response, set `outputFile: true`
       "config": { "type": "request", "url": "https://api.example.com/report" }
     },
     {
-      "id": "generateReport",
+      "id": "createCsv",
       "config": {
         "type": "transform",
         "transformCode": "(sourceData) => ({ __files__: { \"report.csv\": Papa.unparse(sourceData.fetchData.data) } })"

package/skills/superglue/references/http.md

@@ -164,7 +164,7 @@ XML responses are parsed into a JSON tree with ALL tag names normalized to UPPER
 
 Non-2xx responses throw with method, URL, response body preview (1000 chars), masked config, and retry count. Any response with status in the 2xx range is treated as success and returned to the step as-is — the runtime does not scan successful response bodies for error fields, so APIs that return HTTP 200 with `{ "error": "..." }` must be handled by your transform or by setting a `stopCondition`/assertion at the step level.
 
-Bypass: set `failureBehavior: "continue"` to skip the non-2xx throw and return the response anyway.
+Set step-level `failureBehavior: "continue"` to keep the workflow running after a non-2xx failure. The failure remains in `stepResults`.
 
 ### Retry Behavior
 
@@ -249,7 +249,7 @@ When an HTTP step downloads a file (PDF, CSV, binary response), set `outputFile:
 ## Common Pitfalls
 
 - Hardcoding base URLs instead of using `<<systemId_url>>`.
-- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the system's `url` exactly as stored, which may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
+- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the selected credential's `url` override when set, else the system's `url`, exactly as stored — it may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
 - Forgetting auth headers entirely — nothing is injected automatically, including for OAuth systems (only token refresh is automatic)
 - Forgetting `outputFile: true` on steps that download files the user wants
 - Putting pagination variables in the config but not setting a `pagination` block, or vice versa

package/skills/superglue/references/mongodb.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
 
 ### Fields

package/skills/superglue/references/mssql.md

@@ -15,6 +15,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields
@@ -224,7 +226,7 @@ Defaults are tuned for Azure SQL; on-prem servers usually need adjustments:
 - **Self-signed certificates** — on-prem servers rarely have CA-signed certs, so the default `trustServerCertificate=false` fails the TLS handshake. Add `?trustServerCertificate=true` (keeps encryption, skips CA validation).
 - **Old SQL Server versions** — SQL Server 2008/2008 R2 without TLS 1.2 patches cannot complete a modern TLS handshake. Use `?encrypt=false` as a last resort, preferably only over the Secure Gateway tunnel.
 - **Named instances** — use the `?instanceName=` query parameter (see URL Format above); remember SQL Browser (UDP 1434) is required for instance resolution and does not work through the Secure Gateway tunnel.
-- **Firewalled servers** — on-prem databases are typically not internet-reachable; configure the system with a Secure Gateway tunnel.
+- **Firewalled servers** — on-prem databases are typically not internet-reachable; configure the system with a Secure Gateway tunnel. Direct users to the setup guide at https://superglue.ai/docs/guides/secure-gateway/ — do not describe the setup flow from memory.
 
 ### Retry Behavior
 

package/skills/superglue/references/odbc.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields

package/skills/superglue/references/postgres.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
 ### Fields

package/skills/superglue/references/redis.md

@@ -13,6 +13,8 @@
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
 
 ### Fields

package/skills/superglue/references/sftp-smb.md

@@ -15,6 +15,8 @@ FTP, SFTP, and SMB share an identical operation interface. Only the URL protocol
 
 Configure the connection URL based on the selected credential's secrets — use `sg system find` to inspect the available secret names and reference them accordingly.
 
+`<<systemId_url>>` resolves to the selected credential's `url` override when one is set, else to the system `url`. Use it as the full connection string when each tenant has its own host; set the override with `sg system credentials set --url`.
+
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for file server steps.
 
 ### Fields

package/skills/superglue/references/superglue-info.md

@@ -69,7 +69,6 @@ The persistent left sidebar contains these top-level items:
 - **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
 - **Control Panel** (`/admin`) — expandable group for organization and account administration:
   - **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
-  - **Landscape** (`/landscape`) — graph overview of tools, systems, and their connections.
   - **Schedules** (`/admin?view=schedules`) — scheduled and recurring tool runs.
   - **Access Rules** (`/admin/access`) — role and access-rule configuration; visible to admins on paid tiers. Use the access-rules reference for RBAC behavior, base roles, and personal roles.
   - **Organization** (`/organization`) — visible on paid tiers as a standalone page without tabs. It shows members, invitations, role assignment, and member-management actions; management actions are admin-gated.