@superglue/cli 1.1.31 → 1.1.33

package/dist/skills/superglue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 SKILL.md, also run `sg skill <topic>` for the specific protocols and topics involved."
+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 either that it is configured with sg login or, for headless/API-key auth, that SUPERGLUE_API_KEY and SUPERGLUE_API_ENDPOINT environment variables are set. If not, guide the user through setup first. After reading SKILL.md, also run `sg skill <topic>` for the specific protocols and topics involved."
 ---
 
 # superglue CLI (`sg`) — Agent Reference
@@ -23,6 +23,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 | `sg skill mssql`          | MSSQL / Azure SQL connection URLs, schema introspection, parameterized queries                       |
 | `sg skill odbc`           | ODBC connections (SAP ASE / Sybase via FreeTDS), driver config, positional `?` params                |
 | `sg skill redis`          | Redis command syntax, connection URLs, key type handling                                             |
+| `sg skill mongodb`        | MongoDB connection URLs (mongodb:// / mongodb+srv://), CRUD operations, Extended JSON, aggregation   |
 | `sg skill sftp-smb`       | SFTP, FTP, and SMB operations, file upload/download semantics, path handling                         |
 | `sg skill file-handling`  | File detection, parsing, `file::` reference syntax, lazy base64 access, transform-produced files     |
 | `sg skill access-rules`   | RBAC roles, resource grants, and tool/system permissions (enterprise only)                           |
@@ -33,7 +34,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 
 1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install: `npm install -g @superglue/cli`.
 2. **Keep CLI and SDK up to date**: Always use the latest versions. Run `sg update` to update the CLI. For the SDK, run `npm install @superglue/client@latest` (JS) or `pip install --upgrade superglue-client` (Python).
-3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg init` (see Setup below). For custom/self-hosted instances, the CLI must know both the instance API endpoint and an org-scoped API key.
+3. **Verify configuration**: Run `sg whoami` or `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg login` (see Setup below). For custom/self-hosted instances, the CLI must know the instance API endpoint; browser login also needs the web app endpoint when it differs from the API URL. Use API-key auth only for headless/legacy environments.
 
 **Calling systems and running tools**
 
@@ -53,7 +54,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 
 **Non-interactive environments (AI agents, CI)**
 
-- Pass ALL credentials (including secrets) directly via `--credentials '{"api_key":"sk-xxx"}'`. Ask the user for secret values, then include them in the JSON.
+- Pass all secret values directly via `--credentials '{"api_key":"sk-xxx"}'`. Ask the user for secret values, then include them in the JSON.
 
 ---
 
@@ -67,26 +68,22 @@ npm install -g @superglue/cli
 
 After installation the `sg` command is available globally.
 
-### Initialization
+### Authentication
 
-The CLI will not work until configured with an API key. The endpoint defaults to `https://api.superglue.cloud`.
+The preferred CLI setup is browser OAuth via `sg login`. Headless/API-key auth is available for CI and legacy automation. The API endpoint defaults to `https://api.superglue.cloud`.
 
-**Interactive (humans):**
+**Browser login (humans):**
 
 ```bash
-sg init
+sg login
+sg --endpoint "https://custom-api.example.com" login --web-endpoint "https://custom-app.example.com" --save-config
 ```
 
-Prompts for: API key (required — get one at https://app.superglue.cloud/api-keys), API endpoint, web endpoint (for OAuth callbacks), output mode (`stdout` or `stdout+file`), and config location (project-local `.superglue/config.json` vs global `~/.superglue/config.json`). Verifies the connection before saving.
+Opens the browser, completes OAuth login, and stores the OAuth session in `~/.superglue/auth.json`. This file is separate from `config.json`. Use `--save-config` to persist non-secret endpoint settings in `config.json`, and `sg logout` to remove the OAuth session.
 
-**Non-interactive (CI, agents):**
+**Headless/API-key auth (CI, agents, backwards-compatible):**
 
-```bash
-sg init --api-key "your-api-key" --global
-sg init --api-key "your-api-key" --endpoint "https://custom.endpoint.com" --global
-```
-
-`--api-key` and `--endpoint` are global flags and work on all subcommands.
+Use environment variables, global flags, or an existing `.superglue/config.json`. `sg init` remains available as a legacy hidden command for scripts that already use it, but new setup should prefer `sg login` for humans and env vars/config files for headless API-key auth.
 
 **Environment variables (no config file):**
 
@@ -95,13 +92,13 @@ export SUPERGLUE_API_KEY="your-api-key"
 export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud"   # optional, this is the default
 ```
 
-**Config resolution order:** CLI flags > environment variables > local `.superglue/config.json` > global `~/.superglue/config.json`.
+**Config resolution order:** CLI flags > environment variables > local `.superglue/config.json` > global `~/.superglue/config.json`. For authentication, API keys from flags/env/config take precedence; if no API key is configured, the CLI uses the matching OAuth session from `~/.superglue/auth.json`.
 
-Verify with `sg system list` — should return a list (possibly empty) without errors.
+Verify with `sg whoami` or `sg system list` — should return authenticated context without errors.
 
 ### Capability Presets
 
-Set during `sg init` or via `SUPERGLUE_CLI_PRESET` env var. Stored in `config.json` as `"preset"`.
+Set via `SUPERGLUE_CLI_PRESET` env var or `config.json` as `"preset"`. Legacy `sg init --preset` still writes this value for existing scripts.
 
 | Preset    | Description                                                                                    |
 | --------- | ---------------------------------------------------------------------------------------------- |
@@ -127,7 +124,7 @@ Blocked commands print a clear error showing the current preset and how to chang
 ### Building a Tool
 
 1. **Load relevant protocol references** via `sg skill <topic>` based on the systems involved (http, postgres, graphql, etc.)
-2. Use `sg system find` for every involved system — note `storedCredentials` and the system URL
+2. Use `sg system find` for every involved system — note the available secret names and the system URL
 3. Use `sg system search-docs` for each system — look up endpoints, auth patterns, pagination, response structure
 4. Use `sg system call` to test 1-2 primary endpoints — verify response structure and field names before building
 5. Call `sg tool build --config '{...}'` with the full tool config (see Reference → Tool Config Schema)
@@ -148,7 +145,7 @@ Blocked commands print a clear error showing the current preset and how to chang
 1. Search for an existing system first: `sg system find <query>`
 2. If creating: `sg system create --name "..." --url "..." --credentials '{...}'`. Prefer `--template <id>` when one exists — it auto-fills URL and OAuth config
 3. For OAuth: `sg system oauth --system-id <id> [--scopes "..."]` opens a browser flow. User approves → tokens saved automatically
-4. For user-owned non-OAuth credentials: `sg system credentials set --system-id <id> --credentials '{...}'`
+4. For non-OAuth secrets: `sg system credentials set --system-id <id> --credentials '{...}'`
 5. Verify connectivity with `sg system call`
 6. For updates: `sg system edit --id <id>` with the fields to change
 
@@ -222,8 +219,8 @@ Agents familiar with the web tool names can map them directly to CLI commands:
 | `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`                                         |
-| `run_command` with `vfs` for `/org/systems/`     | `sg system find <query>` / `--id <id>`         | Returns `storedCredentials` and system URL                         |
-| Credentials VFS / user-owned credentials         | `sg system credentials get/set/clear`          | Manage current user's credentials for user-owned systems           |
+| `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      |
 | `run_command search`                             | `sg system search-docs --system-id <id> -k`    | Targeted keyword search over ingested system docs                  |
 | `authenticate_oauth`                             | `sg system oauth --system-id <id> [--scopes]`  | Opens browser flow. Supports `--grant-type client_credentials` too |
@@ -233,13 +230,17 @@ Agents familiar with the web tool names can map them directly to CLI commands:
 | `edit_mcp_server`                                | `sg mcp edit --id <id> ...`                    | Edits name, auth mode, description, or selected tool IDs           |
 | `create_schedule`                                | `sg schedule create --tool <id> --cron <expr>` | Creates a cron schedule for a saved tool                           |
 | `edit_schedule`                                  | `sg schedule edit --tool <id> --id <schedule>` | Updates, enables, or disables an existing schedule                 |
-| (no direct equivalent)                           | `sg init`, `sg update`, `sg skill`             | CLI-specific setup, updater, and this reference system             |
+| (no direct equivalent)                           | `sg login`, `sg update`, `sg skill`            | CLI-specific setup, updater, and this reference system             |
 
 Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `authenticate_oauth`'s dedicated MCP `authenticate` tool (CLI uses `sg system oauth`).
 
 ### Command Reference
 
-**`sg init`** — Interactive or non-interactive setup. Creates `.superglue/` config. Flags: `--api-key`, `--endpoint`, `--preset`, `--global`.
+**`sg login`** — Browser OAuth setup. Stores the OAuth session in `~/.superglue/auth.json`. Flags: `--web-endpoint`, `--no-browser`, `--save-config`, `--global`. Use global `--endpoint` for custom/self-hosted API URLs.
+
+**`sg logout`** — Removes the stored OAuth session from `~/.superglue/auth.json`.
+
+**`sg whoami`** — Shows the authenticated superglue user and organization.
 
 **Tool commands:**
 
@@ -335,7 +336,7 @@ Attach files with repeatable `--file key=path`. Reference in payloads with `file
 }
 ```
 
-**Request step fields** (HTTP, Postgres, MSSQL, Redis, FTP/SFTP, SMB) — see protocol-specific references for full details:
+**Request step fields** (HTTP, Postgres, MSSQL, Redis, MongoDB, FTP/SFTP, SMB) — see protocol-specific references for full details:
 
 | Field         | Type   | Description                                                              |
 | ------------- | ------ | ------------------------------------------------------------------------ |
@@ -377,7 +378,8 @@ All step config fields (url, headers, body, queryParams) support `<<expression>>
 <<page>> <<offset>> <<cursor>> <<limit>> <<pageSize>>   pagination variables
 <<systemId_api_key>>   system credentials (namespaced: systemId_credKey)
 <<systemId_url>>       system base URLs (namespaced: systemId_url)
-<<sg_auth_email>>      email of the authenticated user (NOT available in scheduled runs)
+<<sg_auth_email>>      email of the user triggering this run (in scheduled runs: the schedule creator)
+<<sg_auth_jwt>>        short-lived signed JWT proving the identity of the user triggering this run; receivers verify it against superglue's outbound JWKS endpoint (/api/auth/outbound-jwks on the web app origin)
 ```
 
 Simple `<<varName>>` only works for top-level keys. No dots, no nesting. `<<currentItem.id>>`, `<<sourceData.userId>>`, `<<user.name>>` all FAIL at runtime.
@@ -422,7 +424,7 @@ sourceData = {
 
 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` — injected by the runtime
+- `__files__`, `currentItem`, `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
@@ -490,10 +492,10 @@ All user-provided JS runs in an isolated Deno sandbox.
 
 ### Credentials and Systems
 
-Credentials are namespaced as `<<systemId_credentialKey>>` and resolved server-side at execution time. You MUST explicitly reference them:
+Secrets are referenced by name as `<<systemId_credentialKey>>` and resolved from the selected credential at execution time. You MUST explicitly reference them:
 
 ```
-System id="stripe", storedCredentials: api_key → "sk_proj****"
+System id="stripe", selected credential has secret named: api_key
 → Available as: <<stripe_api_key>>
 ```
 
@@ -516,11 +518,11 @@ Basic auth auto-encodes: if the value after `Basic ` isn't already base64, the e
 
 **Credential lifecycle:**
 
-- Pass ALL credentials (including secrets) via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
-- For user-owned systems, use `sg system credentials set --system-id <id> --credentials '{...}'` to save credentials for the current API-key user
-- Use `sg system credentials get --system-id <id>` to inspect current-user credential keys; values are masked unless `--reveal` is passed
+- Pass all secret values via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
+- Use `sg system credentials set --system-id <id> --credentials '{...}'` to save secrets in the current API-key user's credential
+- Use `sg system credentials get --system-id <id>` to inspect the current user's secret names and whether each has a non-empty value; secret values are never returned
 - OAuth tokens (`access_token`, `refresh_token`) auto-refresh before each step execution
-- Non-sensitive fields (`client_id`, `auth_url`, `token_url`) are stored alongside secrets in the same `--credentials` JSON
+- Non-sensitive fields (`client_id`, `auth_url`, `token_url`) can be submitted alongside secrets in the same `--credentials` JSON
 
 **System IDs:** lowercase letters, numbers, underscores only — no hyphens. Used for credential namespacing.
 
@@ -586,7 +588,7 @@ Drafts live under the active CLI config directory: local `.superglue/drafts/` wh
 
 After building and saving, tools can be invoked from code via REST API, SDK, or webhook. See `sg skill integration` for complete SDK (TypeScript/Python), REST API, and webhook examples including retry patterns.
 
-**IP whitelisting:** if a customer's system requires IP whitelisting (firewall rules, security groups, etc.), superglue's outbound IPs are `34.234.12.178` and `18.198.191.215`.
+**IP whitelisting:** if a customer's system requires IP whitelisting for firewall rules, security groups, or vendor access controls, superglue Cloud outbound requests come from `34.234.12.178` and `18.198.191.215`. These IPs apply to superglue Cloud only; self-hosted and enterprise deployments use deployment-specific networking.
 
 Quick reference:
 
@@ -622,14 +624,13 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 - **Double-encoded JSON** — when the body contains nested/stringified JSON (e.g. LLM APIs), have `<<>>` expressions return a string via `JSON.stringify(...)`, and use a single expression for the whole body rather than mixing `<<>>` with static JSON
 - **POST for read-only ops** — GraphQL queries via POST should have `modify: false`. Don't rely on HTTP method alone
 - **Saving without approval** — always present `sg tool run` results and ask before `sg tool save`
-- **`sg_auth_email` in scheduled runs** — not available in scheduler-triggered executions. Tools using `<<sg_auth_email>>` will fail
 - **Reserved key collisions** — payload inputs or step ids named after reserved/injected keys (see Naming Rules) are rejected at save time; pick a different name instead of retrying
 
 ---
 
 ## Error Recovery
 
-For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, GraphQL, SFTP/SMB), run `sg skill <protocol>`. General strategies below.
+For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, GraphQL, SFTP/SMB), run `sg skill <protocol>`. General strategies below.
 
 ### Tool build fails validation
 
@@ -639,14 +640,14 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, GraphQL, SFT
 
 1. Re-run with `--include-step-results` to see raw per-step responses and `data` fields
 2. Use `sg system call` to test the failing endpoint directly — isolates step config vs system/auth issues
-3. Use `sg system find --id <systemId>` to verify `storedCredentials` keys match what the step references
+3. Use `sg system find --id <systemId>` to verify the stored secret names match what the step references
 4. For HTTP: run `sg skill http` and follow the error recovery section (endpoint vs system isolation, credential scopes, rate limiting)
 5. For databases: run `sg skill postgres` or `sg skill mssql` — SSL/TLS and schema issues are common causes
 6. Use `sg system search-docs` and web search to verify the current API shape. APIs change across versions
 
 ### Authentication failures
 
-1. Run `sg system find --id <systemId>` → check `storedCredentials` for masked but present values
+1. Run `sg system find --id <systemId>` → check which secret names are present and whether they have non-empty values
 2. For OAuth: re-run `sg system oauth` if tokens are missing or expired
 3. For custom OAuth: verify `client_id`, `client_secret`, `auth_url`, `token_url` are all present. Confirm the redirect URI is registered on the provider's OAuth app
 4. Check scopes — 403 / empty responses often mean the token lacks required scopes

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

@@ -44,7 +44,7 @@ N/A — file handling is a runtime behavior, not a protocol. Authentication is h
 
 Every response is read as raw bytes. The runtime classifies it using this priority chain:
 
-1. **Magic-byte detection** — known binary signatures (ZIP `PK\x03\x04`, PDF `%PDF`, GZIP `\x1f\x8b`, plus internal ZIP structure checks for Excel/DOCX)
+1. **Magic-byte detection** — known binary signatures (ZIP `PK\x03\x04`, PDF `%PDF`, GZIP `\x1f\x8b`, plus internal ZIP structure checks for Excel/DOCX/PPTX)
 2. **`Content-Disposition: attachment`** — `attachment` or `filename=` in this header forces file treatment
 3. **`application/octet-stream`** — explicit octet-stream MIME catches unlabeled binary payloads
 4. **25MB size fallback** — only when byte detection returned `RAW`, the response exceeds 25MB, and `Content-Type` is not text-like (`text/*`, `application/json`, `*+json`, `application/xml`)
@@ -53,11 +53,11 @@ File server `get` operations always produce files regardless of detected type.
 
 ### Classification
 
-| Classification      | Types                       | Destination                                                    |
-| ------------------- | --------------------------- | -------------------------------------------------------------- |
-| **Binary**          | PDF, Excel, DOCX, ZIP, GZIP | `producedFiles` + `data` (extracted/parsed content)            |
-| **Structured text** | JSON, XML, CSV, YAML, HTML  | `data` only (parsed to JS objects)                             |
-| **RAW**             | Unrecognized                | File if attachment/octet-stream/25MB fallback, else raw string |
+| Classification      | Types                             | Destination                                                    |
+| ------------------- | --------------------------------- | -------------------------------------------------------------- |
+| **Binary**          | PDF, Excel, DOCX, PPTX, ZIP, GZIP | `producedFiles` + `data` (extracted/parsed content)            |
+| **Structured text** | JSON, XML, CSV, YAML, HTML        | `data` only (parsed to JS objects)                             |
+| **RAW**             | Unrecognized                      | File if attachment/octet-stream/25MB fallback, else raw string |
 
 Binary responses expose `stepFileKeys` and populate `sourceData.__files__`. Structured text responses only populate `sourceData.stepId.data`.
 
@@ -73,10 +73,13 @@ Binary responses expose `stepFileKeys` and populate `sourceData.__files__`. Stru
 | Excel | Object keyed by sheet name, each value is array of row objects |
 | PDF   | `{ textContent, structuredContent: [{ page, text }] }`         |
 | DOCX  | Markdown string                                                |
+| PPTX  | Plain text, separated by slide                                 |
 | ZIP   | Object keyed by entry filename, each value recursively parsed  |
 | GZIP  | Recursively parsed inner content                               |
 | RAW   | UTF-8 string fallback                                          |
 
+**PPTX rules:** extraction includes slide text, including text inside basic tables. It does not include images, charts, layout, animations, or speaker notes.
+
 **Excel rules:**
 
 - Excel is never a flat array. It is always `{ "SheetName": [ {row}, ... ] }` — even for single-sheet files

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

@@ -68,8 +68,15 @@ Some APIs (e.g. Salesforce) use SOAP XML login where credentials are embedded in
 
 `<<systemId_password>><<systemId_security_token>>` resolves to the password and token concatenated — no separator needed. This works in URL, headers, and body fields.
 
-Headers starting with `x-` are treated as custom headers.
-Modern APIs expect auth in headers, not query parameters, unless docs explicitly say otherwise.
+### Parsing XML responses
+
+XML responses (SOAP and other XML APIs) are auto-parsed to an object on `sourceData.stepId.data`. The parser has quirks you MUST account for in transforms and stopConditions — probe the real response with a small page before writing selectors:
+
+- **Every tag name is UPPERCASED.** `<response><record>` becomes `RESPONSE.RECORD`, regardless of the source casing. Always select uppercase keys.
+- **Single vs multiple children collapse.** One child element parses to an object; multiple with the same tag parse to an array. Normalize before mapping: `const rows = Array.isArray(x) ? x : (x ? [x] : [])`.
+- **Element attributes become keys on the element object** (also uppercased). `<data count="2" total="127">` gives `DATA.COUNT` and `DATA.TOTAL` alongside the child records.
+- **Text with attributes goes to `_TEXT`.** An element with both attributes and text content stores the text under a `_TEXT` key. Empty elements (`<field></field>`) become `{}`.
+- **Numbers and booleans are strings.** Everything is a string; wrap with `Number(...)` where you need arithmetic.
 
 ## HTTP Runtime Details
 
@@ -143,11 +150,15 @@ Multipart restrictions:
 
 All HTTP responses are read as raw bytes, then classified by byte-level detection (see `file-handling.md` for the full detection logic).
 
-- **Binary types** (PDF, Excel, DOCX, ZIP, GZIP): treated as files, parsed content also populates `data`. Later steps can reference via `file::<stepId>.raw/base64/extracted`.
+- **File responses**: formats classified as files by `file-handling.md` are stored as files, and parsed content populates `data` when extraction is available. Later steps can reference them via `file::<stepId>.raw/base64/extracted`.
 - **`application/octet-stream`**: always treated as a file.
 - **Responses over 25 MB**: treated as files as a safety fallback.
 - **RAW + `Content-Disposition: attachment`**: treated as a file.
-- **Structured/text responses** (JSON, XML, CSV, YAML, HTML, text under size limit): parsed inline to `data` only.
+- **Inline responses**: formats classified as structured or plain text by `file-handling.md` populate `data` without producing a stored file unless another file rule applies.
+
+### XML Response Casing
+
+XML responses are parsed into a JSON tree with ALL tag names normalized to UPPERCASE — the parsed keys will not match the raw document's casing. This applies identically to `sg system call` and to request steps in tools. A raw `fetch()` inside a transform step is the exception: it returns the original document with its real casing (often lowercase envelope tags with uppercase field tags). Never write string-level XML parsing logic in a transform from memory of what `sg system call` showed — capture a raw probe first (e.g. return `{ rawXml: xml.slice(0, 1500) }`), and guard against self-closing empty containers (`<data/>` has no closing tag) and repeated sibling result blocks.
 
 ### Error Detection
 

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

@@ -0,0 +1,136 @@
+# MongoDB
+
+## Step Configuration
+
+```typescript
+{
+  type: "request",
+  systemId: "my_mongo",
+  url: "mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin",
+  body: '{"collection": "users", "operation": "find", "filter": {"status": "active"}, "options": {"limit": 50, "sort": {"createdAt": -1}}}'
+}
+```
+
+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.
+
+`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
+
+### Fields
+
+| Field      | Required | Notes                                                          |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `url`      | yes      | Connection string with `<<credential>>` placeholders           |
+| `body`     | yes      | JSON: single operation object or array of operations           |
+| `systemId` | no       | Links system credentials for `<<systemId_credKey>>` resolution |
+
+### URL Format
+
+```
+mongodb://user:password@host:port/database?authSource=admin
+mongodb+srv://user:password@cluster.example.mongodb.net/database   (SRV seedlist, e.g. Atlas)
+```
+
+- `mongodb://` for a standard host:port connection.
+- `mongodb+srv://` for DNS SRV seedlists (MongoDB Atlas). The driver resolves the seedlist and enables TLS automatically; do not add a port.
+- The default database comes from the URL path; override per operation with a `database` field in the body.
+- Common query params: `authSource` (auth database, usually `admin` for root users), `replicaSet`, `tls`, `retryWrites`.
+- Special characters in the username or password are URL-encoded automatically before the driver parses the string.
+
+### Body Format
+
+JSON string with `operation` (required) and `collection` (required for all operations except `listCollections`). Bodies are parsed as MongoDB Extended JSON, so `{ "$oid": "..." }` becomes an `ObjectId` and `{ "$date": "..." }` becomes a `Date`:
+
+```json
+{
+  "collection": "orders",
+  "operation": "find",
+  "filter": { "_id": { "$oid": "652c1f77bcf86cd799439011" } }
+}
+```
+
+For several operations in one step, pass an array (executed in order, results returned as an array):
+
+```json
+[
+  { "collection": "orders", "operation": "countDocuments", "filter": { "status": "paid" } },
+  {
+    "collection": "orders",
+    "operation": "find",
+    "filter": { "status": "paid" },
+    "options": { "limit": 10 }
+  }
+]
+```
+
+### Supported Operations
+
+| Operation                                                     | Required fields                                   | Returns                                        |
+| ------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
+| `find`                                                        | `collection`                                      | array of documents                             |
+| `findOne`                                                     | `collection`                                      | a document or `null`                           |
+| `aggregate`                                                   | `collection`, `pipeline`                          | array of documents                             |
+| `countDocuments`                                              | `collection`                                      | number                                         |
+| `estimatedDocumentCount`                                      | `collection`                                      | number                                         |
+| `distinct`                                                    | `collection`, `field`                             | array of values                                |
+| `listCollections`                                             | —                                                 | array of collection info                       |
+| `insertOne`                                                   | `collection`, `document`                          | `{ acknowledged, insertedId }`                 |
+| `insertMany`                                                  | `collection`, `documents`                         | `{ acknowledged, insertedCount, insertedIds }` |
+| `updateOne` / `updateMany`                                    | `collection`, `filter`, `update`                  | `{ matchedCount, modifiedCount, upsertedId }`  |
+| `replaceOne`                                                  | `collection`, `filter`, `replacement`             | update result                                  |
+| `deleteOne` / `deleteMany`                                    | `collection`, `filter`                            | `{ acknowledged, deletedCount }`               |
+| `findOneAndUpdate` / `findOneAndReplace` / `findOneAndDelete` | `collection`, `filter` (+ `update`/`replacement`) | the affected document                          |
+| `bulkWrite`                                                   | `collection`, `operations`                        | bulk write result                              |
+
+`filter`, `pipeline`, `document`, `update`, `replacement`, and driver `options` (e.g. `limit`, `skip`, `sort`, `projection`, `upsert`) are passed straight through to the driver.
+
+Dynamic values with variables:
+
+```json
+{
+  "collection": "users",
+  "operation": "find",
+  "filter": { "orgId": "<<(sourceData) => sourceData.orgId>>" }
+}
+```
+
+## Authentication
+
+Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically. Root/admin users almost always need `?authSource=admin`.
+
+```
+mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin
+```
+
+## MongoDB Runtime Details
+
+### Return Values
+
+Documents are returned as Extended JSON (relaxed): an `ObjectId` becomes `{ "$oid": "..." }` and a `Date` becomes `{ "$date": "..." }`. Query those values back with the same form. A single operation returns its result directly; an array of operations returns an array of results in order.
+
+### Connection Management
+
+- Clients are reused per connection string within a run and closed after completion.
+- TLS is automatic for `mongodb+srv://` and when the connection string sets `tls=true`.
+- Connection timeout defaults to 30 seconds; operation/socket timeout follows the system/protocol timeout.
+
+### Retry Behavior
+
+Default retries come from server config. On final failure, the error includes the failing operation name.
+
+## Common Pitfalls
+
+- Omitting `?authSource=admin` when authenticating as a root user — auth fails with "Authentication failed".
+- Adding a port to a `mongodb+srv://` URL — SRV connection strings must not include a port.
+- Passing an `_id` as a plain string when the document stores an `ObjectId` — wrap it as `{ "$oid": "..." }` so it matches.
+- Putting `limit`/`sort`/`projection` at the top level — they belong inside `options`.
+- Accessing the step result directly instead of via `.data` — MongoDB results follow the same envelope as all steps: `sourceData.stepId.data`.
+
+## Error Recovery
+
+When a MongoDB step fails:
+
+1. **Read the error message** — superglue includes the operation name in the error. Check for unknown operations, missing required fields (`filter`, `update`, `pipeline`), or malformed Extended JSON.
+2. **Verify connection secrets** — use `sg system find` to confirm the stored secret names match the placeholders in your URL. Test with a `listCollections` operation via `sg system call`.
+3. **Check auth source** — "Authentication failed" usually means a missing or wrong `authSource`. Root users authenticate against `admin`.
+4. **Check connectivity** — connection refused or server-selection timeouts mean the host is unreachable, the SRV record can't resolve, or an IP allowlist (Atlas) is blocking you. `mongodb+srv://` requires outbound DNS.
+5. **Check the operation shape** — read operations (`find`, `countDocuments`, `distinct`) never mutate; write operations require their specific fields. `aggregate` is read-only unless its pipeline contains a `$out` or `$merge` stage, which writes results back to a collection. Confirm `filter`/`update`/`pipeline` are objects/arrays, not strings.

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

@@ -13,7 +13,7 @@
 }
 ```
 
-Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+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.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
@@ -93,46 +93,46 @@ mssql://<<my_db_user>>:<<my_db_password>>@<<my_db_host>>:<<my_db_port>>/<<my_db_
 
 ### Windows Authentication (NTLM)
 
-For on-prem SQL Servers that only accept Windows domain logins (no SQL auth), store these credential keys on the system:
+For on-prem SQL Servers that only accept Windows domain logins (no SQL auth), add secrets with these names to the credential:
 
-| Credential Key | Required | Notes                                                 |
-| -------------- | -------- | ----------------------------------------------------- |
-| `authType`     | yes      | `ntlm`                                                |
-| `domain`       | yes      | Windows domain (e.g. `CORP`)                          |
-| `user`         | yes      | Windows username (also accepts `username`, or in URL) |
-| `password`     | yes      | Windows password (or in URL)                          |
+| Secret Name | Required | Notes                                                 |
+| ----------- | -------- | ----------------------------------------------------- |
+| `authType`  | yes      | `ntlm`                                                |
+| `domain`    | yes      | Windows domain (e.g. `CORP`)                          |
+| `user`      | yes      | Windows username (also accepts `username`, or in URL) |
+| `password`  | yes      | Windows password (or in URL)                          |
 
 ```
 URL:  mssql://<<sys_user>>:<<sys_password>>@<<sys_host>>:<<sys_port>>/<<sys_database>>
-Credentials: { authType: "ntlm", domain, user, password, host, port, database }
+Secrets: { authType: "ntlm", domain, user, password, host, port, database }
 ```
 
 Alternatively, pass the domain as a `?domain=CORP` query parameter on the URL — any URL with a `domain` set authenticates via NTLM. Kerberos-only environments are not supported; ask the DBA to permit NTLM or create a SQL login.
 
 ### Azure Active Directory Authentication
 
-For Azure AD auth, store the following credential keys on the system alongside the standard connection fields:
+For Azure AD auth, add secrets with the following names to the credential alongside the standard connection fields:
 
 **Entra ID User + Password** — authenticates as an Azure AD user. Requires an Azure app registration.
 
-| Credential Key | Required | Notes                                                  |
-| -------------- | -------- | ------------------------------------------------------ |
-| `authType`     | yes      | `azure-active-directory-password`                      |
-| `clientId`     | yes      | Application (client) ID from Azure app registration    |
-| `tenantId`     | no       | Directory (tenant) ID                                  |
-| `user`         | yes      | Azure AD username (also accepts `username`, or in URL) |
-| `password`     | yes      | Azure AD password (or in URL)                          |
+| Secret Name | Required | Notes                                                  |
+| ----------- | -------- | ------------------------------------------------------ |
+| `authType`  | yes      | `azure-active-directory-password`                      |
+| `clientId`  | yes      | Application (client) ID from Azure app registration    |
+| `tenantId`  | no       | Directory (tenant) ID                                  |
+| `user`      | yes      | Azure AD username (also accepts `username`, or in URL) |
+| `password`  | yes      | Azure AD password (or in URL)                          |
 
-`user` and `password` can be stored as credentials or embedded in the URL — values resolved into the URL take precedence; stored credentials only fill gaps the URL omits.
+`user` and `password` can be stored as secrets or embedded in the URL — values resolved into the URL take precedence; stored secrets only fill gaps the URL omits.
 
 ```
 URL:  mssql://<<sys_user>>:<<sys_password>>@myserver.database.windows.net:1433/mydb
-Credentials: { authType, clientId, tenantId, user, password, host, port, database }
+Secrets: { authType, clientId, tenantId, user, password, host, port, database }
 ```
 
 **Service Principal** — authenticates as an Azure AD application. No user/password needed in the URL.
 
-| Credential Key | Required | Notes                                             |
+| Secret Name    | Required | Notes                                             |
 | -------------- | -------- | ------------------------------------------------- |
 | `authType`     | yes      | `azure-active-directory-service-principal-secret` |
 | `clientId`     | yes      | Application (client) ID                           |
@@ -141,7 +141,7 @@ Credentials: { authType, clientId, tenantId, user, password, host, port, databas
 
 ```
 URL:  mssql://myserver.database.windows.net:1433/mydb
-Credentials: { authType, clientId, clientSecret, tenantId, host, port, database }
+Secrets: { authType, clientId, clientSecret, tenantId, host, port, database }
 ```
 
 The runtime authenticates entirely via the service principal credentials — no user or password is needed in the URL.
@@ -245,7 +245,7 @@ Default retries from server config. On final failure, error includes query text
 When an MSSQL step fails and the cause is not obvious:
 
 1. **Read the error message** — superglue includes the query text and params in the error. Check for syntax errors, missing columns, or type mismatches.
-2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+2. **Verify connection secrets** — use `sg system find` to confirm the stored secret names match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
 3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access. Verify with the user that the credentials have the required grants.
 4. **Check Azure-specific issues** — if connecting to Azure SQL:
    - Confirm the client IP is allowed in the Azure SQL firewall rules

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

@@ -11,7 +11,7 @@
 }
 ```
 
-Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+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.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
@@ -185,7 +185,7 @@ For other ODBC-backed databases, look up the database/driver-specific error code
 When an ODBC step fails and the cause is not obvious:
 
 1. **Read the error message** — superglue includes a truncated query preview in the error. Check for syntax errors, missing columns, or type mismatches.
-2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+2. **Verify connection secrets** — use `sg system find` to confirm the stored secret names match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
 3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access. Verify with the user that the credentials have the required grants.
 4. **Check driver availability** — if the error mentions "driver not found", the `DRIVER` query parameter does not match any registered driver in `/etc/odbcinst.ini`. Verify the driver name is correct and the driver is installed in the Docker image.
 5. **Test the query directly** — use `sg system call` with a simplified version of the query to isolate whether the issue is the query itself, the parameters, or the connection.

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

@@ -11,7 +11,7 @@
 }
 ```
 
-Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+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.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
@@ -148,7 +148,7 @@ Default retries from server config. On final failure, error includes query text
 When a PostgreSQL step fails and the cause is not obvious:
 
 1. **Read the error message** — superglue includes the query text and params in the error. Check for syntax errors, missing columns, or type mismatches.
-2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
+2. **Verify connection secrets** — use `sg system find` to confirm the stored secret names match the placeholders in your URL. Test connectivity with a simple `SELECT 1` via `sg system call`.
 3. **Check database-side access** — connection refused or permission denied errors typically mean the database user lacks access to the database, schema, or table. Verify with the user that the credentials have the required grants.
 4. **Test the query directly** — use `sg system call` with a simplified version of the query to isolate whether the issue is the query itself, the parameters, or the connection.
 5. **Check for SSL/TLS issues** — if the error mentions SSL or handshake failure, check the SSL / TLS section above. For non-localhost servers that don't support SSL, add `?sslmode=disable` to the URL. For servers that require SSL, add `?sslmode=require`.

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

@@ -11,7 +11,7 @@
 }
 ```
 
-Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
+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.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
 
@@ -133,7 +133,7 @@ Default retries from server config. On final failure, error includes command and
 When a Redis step fails:
 
 1. **Read the error message** — superglue includes the command and args in the error. Check for unknown commands, wrong argument counts, or type errors (e.g. running a list command on a string key).
-2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test with a simple `PING` command via `sg system call`.
+2. **Verify connection secrets** — use `sg system find` to confirm the stored secret names match the placeholders in your URL. Test with a simple `PING` command via `sg system call`.
 3. **Check connectivity and access** — connection refused errors typically mean the Redis server is unreachable or requires TLS (`rediss://`). AUTH errors mean the password is wrong or the user lacks access.
 4. **Check key types** — Redis commands are type-specific. Running `GET` on a hash key or `HGETALL` on a string key returns a `WRONGTYPE` error. Use `TYPE` command via `sg system call` to check a key's type before building.
 5. **Verify TLS requirements** — if the error mentions connection reset or handshake failure, try switching between `redis://` and `rediss://`.