@superglue/cli 1.1.204 → 1.1.205

package/dist/skills/superglue/SKILL.md

@@ -27,7 +27,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 | `sg skill sftp-smb`       | SFTP, FTP, and SMB operations, file upload/download semantics, path handling                         |
 | `sg skill suitecloud`     | NetSuite SuiteCloud deploys: custom fields, record types, scripts; validate, preview, deploy         |
 | `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)                           |
+| `sg skill access-rules`   | RBAC roles, resource grants, and tool/credential permissions (enterprise only)                       |
 
 ## CRITICAL RULES — READ FIRST
 
@@ -40,7 +40,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
 **Calling systems and running tools**
 
 1. ALWAYS pull the relevant system context using `sg system find` before calling system endpoints and before building tools.
-2. Use `sg system search-docs` for a targeted keyword search of system docs when unsure how a system works.
+2. Consult provider documentation when an API or service behavior is unclear.
 
 **Authentication & Credentials**
 
@@ -101,11 +101,11 @@ Verify with `sg whoami` or `sg system list` — should return authenticated cont
 
 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                                                                                                    |
-| --------- | -------------------------------------------------------------------------------------------------------------- |
-| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing                                             |
-| `builder` | Runner + build/edit/save tools, call systems, manage MCP servers, schedules, and project tasks. No system CRUD |
-| `admin`   | Full access (default)                                                                                          |
+| Preset    | Description                                                                                                 |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `runner`  | Run saved tools by ID only. Read-only lookups. No building/editing                                          |
+| `builder` | Runner + build/edit/save tools, call systems, manage connections, MCP servers, schedules, and project tasks |
+| `admin`   | Full access (default)                                                                                       |
 
 Blocked commands print a clear error showing the current preset and how to change it.
 
@@ -125,8 +125,8 @@ 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 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
+2. Use `sg system find` for every involved system — note the available secret names and the connection URL
+3. Consult provider documentation for endpoints, authentication, pagination, and 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)
 6. Test with `sg tool run --draft <draftId>`. Use `--include-step-results` to inspect raw step data
@@ -141,14 +141,22 @@ Blocked commands print a clear error showing the current preset and how to chang
 4. Apply with `sg tool edit --tool <toolId> --patches '[...]'` (or `--draft <draftId>` for drafts)
 5. Re-run to verify behavior
 
-### Creating/Editing a System
+### Connecting a System
 
-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 non-OAuth secrets: `sg system credentials set --system-id <id> --credentials '{...}'`
+Systems are derived: a connection namespace is derived from existing connections. There is no system record to create or edit; you create and edit your connection.
+
+Removed commands (`sg system create`, `edit`, `credentials`, and `search-docs`) return a deprecation error with `sg update` and replacement guidance. Removed system API endpoints return HTTP 410 with the same guidance. Run `sg update`, then use connection commands; use `sg system find --id <id>` for system knowledge. Legacy `/credentials` API aliases remain available with deprecation headers.
+
+1. Read the relevant tool's namespace first, then inspect existing namespaces with `sg system find <query>` and the connections you can access under one with `sg system connection list --system-id <id>`. Reuse that exact id, even when other users' connections are hidden. For a new namespace, use the template id, not its display name. Without a template, choose a descriptive id. Keep account labels in connection names; separate namespaces when tools need distinct services or environments.
+2. Save your connection under the id: `sg system connection set --system-id <id> --url "..." --credentials '{...}' --authentication '{"type":"api_key"}'`. `--authentication` or `--oauth-app-id` is required when creating a connection; use `{"type":"none"}` for unauthenticated systems. Use the saved connection's returned `systemId` in later commands, tool steps, and placeholders.
+3. For OAuth: discover reusable apps with `sg system oauth-apps [--system-id <id>]` and link one with `--oauth-app-id <id>`. When several apps fit, ask the user which one to use. A new client ID and secret creates a reusable org app automatically, including default scopes. Otherwise add the client config with `--authentication '{"type":"oauth2",...}'`, then `sg system oauth --system-id <id> [--scopes "..."]` opens a browser flow. Omit `--scopes` to use saved connection scopes. Supply it to replace the set, including more or fewer scopes; `--scopes ""` requests none. Overrides are saved on the connection and do not change app defaults. User approves → tokens saved to your connection
+4. For private systems: `--tunnel-id <id>` binds a Secure Gateway tunnel to the connection
 5. Verify connectivity with `sg system call`
-6. For updates: `sg system edit --id <id>` with the fields to change
+6. For updates: re-run `sg system connection set --system-id <id>` with the fields to change. When the namespace holds several connections, pass `--connection-id <id>` from `sg system connection list` to `set`, `clear`, `oauth`, and `call`; without it, `set` and `oauth` target your default or oldest owned connection
+
+A connection linked to an OAuth app uses the app's client ID, client secret, and token URL; app secret rotations reach every linked connection. Other authentication fields are copied on selection and stay connection-specific; scope edits remain local. Changing the client ID or token URL detaches the connection and requires its own client secret; `--oauth-app-id ""` also detaches and must be sent together with the connection's own client secret. Changing client settings retains tokens and supplemental secrets; authorize again afterward. Managed secrets stay hidden and restricted to approved provider endpoints.
+
+When selecting an OAuth app on an existing non-OAuth connection, also pass `--authentication '{"type":"oauth2"}'`. An app-only update to a non-OAuth connection returns a validation error.
 
 ### Running a Tool (Ad-hoc)
 
@@ -235,32 +243,30 @@ sg project task edit --project <projectId> --id <taskId> --labels blocked
 
 Agents familiar with the web agent (its native tools and the `superglue` node module used inside `run_command`) can map them directly to CLI commands:
 
-| Web agent tool                                   | CLI command                                    | Notes                                                              |
-| ------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
-| `tools.writeTool` (superglue module; new id)     | `sg tool build --config '{...}'`               | CLI is not AI-powered — you provide the full JSON config           |
-| `tools.writeTool` (superglue; saved id)          | `sg tool edit --tool <id> --patches '[...]'`   | JSON Patch (RFC 6902). Use `--draft <id>` for drafts               |
-| `tools.runTool`                                  | `sg tool run --tool <id>` / `--draft <id>`     | Add `--include-step-results` to inspect per-step data              |
-| `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        |
-| `tools.writeSystem` (superglue module; new id)   | `sg system create --name "..." --url "..."`    | Use `--template <id>` when available                               |
-| `tools.writeSystem` (superglue; saved)           | `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                 |
-| `tools.callSystem`                               | `sg system call --system-id <id> --url <url>`  | Ad-hoc calls; credential and auth header are added server-side     |
-| `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 |
-| `run_command` with `vfs` for `/org/runs/`        | `sg run list` / `sg run get <runId>`           | Filter `list` by `--tool`, `--status`, `--source`, `--limit`       |
-| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>`        | Returns endpoint, auth mode, selected tool IDs, and client config  |
-| `tools.writeMcpServer` (superglue module; new)   | `sg mcp create --name <n> --tool <id>`         | Creates a named MCP endpoint for selected saved tools              |
-| `tools.writeMcpServer` (superglue)               | `sg mcp edit --id <id> ...`                    | Edits name, auth mode, description, or selected tool IDs           |
-| `tools.writeSchedule` (superglue module; new)    | `sg schedule create --tool <id> --cron <expr>` | Creates a cron schedule for a saved tool                           |
-| `tools.writeSchedule` (superglue; id)            | `sg schedule edit --tool <id> --id <schedule>` | Updates, enables, or disables an existing schedule                 |
-| `run_command` with `vfs` for `/projects/`        | `sg project list` / `sg project task list`     | Tasks are listed in board order with `position`                    |
-| `tools.writeTask` (superglue module; no id)      | `sg project task create --project <id>`        | Same fields; `--position` places the task in its column            |
-| `tools.writeTask` (superglue module; id)         | `sg project task edit --project <p> --id <t>`  | Updates only the given fields, including `--position`              |
-| `tools.writeProjectLabel` (superglue module)     | `sg project label create` / `label edit`       | Same fields; `sg project label delete` has no module equivalent    |
-| (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`), and `setup_gateway` (the gateway install command is created in the web app).
+| Web agent tool                                   | CLI command                                      | Notes                                                                                                    |
+| ------------------------------------------------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `tools.writeTool` (superglue module; new id)     | `sg tool build --config '{...}'`                 | CLI is not AI-powered — you provide the full JSON config                                                 |
+| `tools.writeTool` (superglue; saved id)          | `sg tool edit --tool <id> --patches '[...]'`     | JSON Patch (RFC 6902). Use `--draft <id>` for drafts                                                     |
+| `tools.runTool`                                  | `sg tool run --tool <id>` / `--draft <id>`       | Add `--include-step-results` to inspect per-step data                                                    |
+| `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                                              |
+| `tools.writeConnection`                          | `sg system connection set --system-id <id>`      | Creates or updates your connection under its namespace                                                   |
+| `run_command` with `vfs` for `/org/connections/` | `sg system find <query>` / `--id <id>`           | Returns your connection's secret names, url, and auth type                                               |
+| `/org/connections/<id>.json`                     | `sg system connection list/get/set/clear`        | Manage your connection; `--connection-id` targets a specific one                                         |
+| `tools.callSystem`                               | `sg system call --system-id <id> --url <url>`    | Ad-hoc calls; connection and auth header are added server-side; `--connection-id` matches `credentialId` |
+| `create_connection`                              | `sg system connection set` and `sg system oauth` | Saves configuration and secrets, then opens OAuth when needed                                            |
+| `run_command` with `vfs` for `/org/runs/`        | `sg run list` / `sg run get <runId>`             | Filter `list` by `--tool`, `--status`, `--source`, `--limit`                                             |
+| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>`          | Returns endpoint, auth mode, selected tool IDs, and client config                                        |
+| `tools.writeMcpServer` (superglue module; new)   | `sg mcp create --name <n> --tool <id>`           | Creates a named MCP endpoint for selected saved tools                                                    |
+| `tools.writeMcpServer` (superglue)               | `sg mcp edit --id <id> ...`                      | Edits name, auth mode, description, or selected tool IDs                                                 |
+| `tools.writeSchedule` (superglue module; new)    | `sg schedule create --tool <id> --cron <expr>`   | Creates a cron schedule for a saved tool                                                                 |
+| `tools.writeSchedule` (superglue; id)            | `sg schedule edit --tool <id> --id <schedule>`   | Updates, enables, or disables an existing schedule                                                       |
+| `run_command` with `vfs` for `/projects/`        | `sg project list` / `sg project task list`       | Tasks are listed in board order with `position`                                                          |
+| `tools.writeTask` (superglue module; no id)      | `sg project task create --project <id>`          | Same fields; `--position` places the task in its column                                                  |
+| `tools.writeTask` (superglue module; id)         | `sg project task edit --project <p> --id <t>`    | Updates only the given fields, including `--position`                                                    |
+| `tools.writeProjectLabel` (superglue module)     | `sg project label create` / `label edit`         | Same fields; `sg project label delete` has no module equivalent                                          |
+| (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), `create_connection`'s secure input form (CLI accepts secrets through connection commands), and `setup_gateway` (the gateway install command is created in the web app).
 
 ### Command Reference
 
@@ -290,18 +296,17 @@ sg tool find --id my-tool --fields instruction,inputSchema  # only selected top-
 **System commands:**
 
 ```bash
-sg system create --name "My API" --url https://api.example.com --credentials '{"api_key":"sk-xxx"}'
-sg system create --name "Slack" --template slack
-sg system edit --id my_api --credentials '{...}'
+sg system connection set --system-id my_api --url https://api.example.com --credentials '{"api_key":"sk-xxx"}' --authentication '{"type":"api_key"}'
+sg system connection set --system-id slack --credentials '{}' --authentication '{"type":"oauth2"}'   # template id as system id
 sg system list
 sg system find slack
 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
+sg system connection list --system-id my_api
+sg system connection get --system-id my_api
+sg system connection set --system-id my_api --credentials '{"api_key":"sk-xxx"}'
+sg system connection clear --system-id my_api
 sg system call --system-id my_api --url "<<my_api_url>>/users"
 sg system call --system-id my_api --url https://api.example.com/users --headers '{"X-API-Key":"<<my_api_api_key>>"}'
-sg system search-docs --system-id slack -k "send message channels"
 sg system oauth --system-id gmail --scopes "https://www.googleapis.com/auth/gmail.modify"
 sg system oauth --system-id my_api --grant-type client_credentials --scopes "read write"
 ```
@@ -551,12 +556,12 @@ For each step in order:
 
 All user-provided JS runs in an isolated Deno sandbox.
 
-### Credentials and Systems
+### Connections and placeholders
 
-Secrets are referenced by name as `<<systemId_credentialKey>>` and resolved from the selected credential at execution time. You MUST explicitly reference them:
+Secrets are referenced by name as `<<systemId_credentialKey>>` and resolved from the selected connection at execution time. You MUST explicitly reference them:
 
 ```
-System id="stripe", selected credential has secret named: api_key
+System id="stripe", selected connection has secret named: api_key
 → Available as: <<stripe_api_key>>
 ```
 
@@ -571,40 +576,36 @@ 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 resolve the URL of the exact referenced system ID:
+**Connection URL variables** — use these instead of hardcoding base URLs. They resolve the URL of the selected connection for 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.
+`<<systemId_url>>` resolves to the selected connection's `url`. Set it with `sg system connection 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
-- 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
+- Use `sg system connection set --system-id <id> --credentials '{...}'` to save secrets on the current API-key user's connection
+- Use `sg system connection 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`) can be submitted alongside secrets in the same `--credentials` JSON
 
-**System IDs:** lowercase letters, numbers, underscores only — no hyphens. Used for credential namespacing.
+**System IDs:** a system ID groups connections and resolves tool steps and placeholders. Use existing IDs exactly as written, including case; a tool can reference an ID that no connection uses yet, so create a connection with that exact ID. For a new ID, use the matching template's `id`, such as `hubspot`; otherwise use lowercase letters, digits, and underscores, such as `acme_billing`. The server saves IDs as sent and does not correct them. Do not rename a working system ID to match a template.
 
-**Templates:** auto-populate endpoints and OAuth config. `sg system find` lists available templates.
+**Templates:** matched by system id (or connection url) and supply display and OAuth defaults. `sg system find --id <id>` shows the matched template.
 
 - **Preconfigured OAuth** (no user `client_id`/`client_secret` needed): slack, salesforce, asana, notion, airtable, jira, confluence
 - **Common OAuth templates:** gmail, googleDrive, googleCalendar, googleSheets, slack, salesforce, github, jira, confluence, notion, airtable, hubspot, shopify, dropbox, zoom, microsoft
 
-**Custom OAuth (no template):** must include `client_id`, `client_secret`, `auth_url`, `token_url` in credentials at create time — or add later with `sg system edit`:
+**Custom OAuth (no template):** put the client config on your connection's authentication:
 
 ```bash
-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"}'
+sg system connection set --system-id my_api --url https://api.example.com --credentials '{}' \
+  --authentication '{"type":"oauth2","clientId":"...","clientSecret":"...","authUrl":"https://example.com/oauth/authorize","tokenUrl":"https://example.com/oauth/token"}'
 ```
 
-**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.
-
 ### Tool Editing (JSON Patch)
 
 `sg tool edit` applies RFC 6902 JSON Patch operations. Each operation:
@@ -672,13 +673,13 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
 
 ## Common Pitfalls
 
-- **Guessing API endpoints** — always verify with `sg system search-docs` or `sg system call` first
+- **Guessing API endpoints** — verify against provider documentation, then check uncertain request shapes with `sg system call`
 - **`systemId` in the wrong place** — it belongs inside `step.config.systemId`, not on the step object
 - **`<<(sourceData) => sourceData.payload.X>>`** — payload fields are at root level of `sourceData`, not under `.payload`
 - **`<<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>>`) so tools follow the referenced system's configured URL
+- **Missing auth headers** — credentials are never automatically included in any protocol, including for OAuth connections (only token refresh is automatic)
+- **Hardcoded base URLs** — prefer connection URL variables (`<<systemId_url>>`) so tools follow the selected connection's 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)
@@ -706,7 +707,7 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, Gra
 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
+6. Consult provider documentation and web search to verify the current API shape. APIs change across versions
 
 ### Authentication failures
 
@@ -715,11 +716,11 @@ For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, Gra
 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
 
-### System creation fails
+### Connection save fails
 
-1. Check for an existing system with the same ID — use `sg system edit` to update instead
-2. Ensure `id` uses only lowercase letters, numbers, and underscores (no hyphens)
-3. For templated systems, verify the template ID is correct (`sg system find` lists available templates)
+1. Check for an existing connection under the id with `sg system connection get --system-id <id>`; `set` updates it in place
+2. Ensure the id uses only lowercase letters, numbers, underscores, and hyphens
+3. For templated systems, use the template id as the system id so the template applies
 
 ### Data selector / transform returns wrong data
 

package/dist/skills/superglue/references/access-rules.md

@@ -1,13 +1,13 @@
 # Access Rules (RBAC)
 
-On superglue, roles define active resource grants for tools and systems. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
+On superglue, roles define active resource grants for tools, credentials, playbooks, artifacts, files, and projects. Systems are not a resource: a system id is a plain string on connections and tool steps. Users can have multiple roles. Roles and access rules are only available on enterprise organizations.
 
 ## Data Model
 
 ```typescript
 interface ResourceGrant {
   roleId: string;
-  resourceRef: "tool:<encodedId>" | "system:<encodedId>" | "tool:*" | "system:*";
+  resourceRef: "<kind>:<encodedId>" | "<kind>:*"; // kind: tool | credential | playbook | artifact | file | project
   permissions: Array<"viewer" | "editor">;
   source: "access_rule" | "ownership" | "share";
   grantedByUserId?: string;
@@ -28,10 +28,8 @@ Only active grants where `revokedAt` is empty contribute to access. `editor` imp
 
 ## Resource Refs
 
-- `tool:<encodedToolId>` — one specific tool.
-- `system:<encodedSystemId>` — one specific system.
-- `tool:*` — every current and future tool.
-- `system:*` — every current and future system.
+- `<kind>:<encodedId>` — one specific resource, for example `tool:<toolId>` or `credential:<connectionId>`.
+- `<kind>:*` — every current and future resource of that kind.
 
 Resource ids are URL-encoded inside `resourceRef`; use shared helpers rather than hand-building refs.
 
@@ -48,26 +46,25 @@ Current configured role access and ownership grants are generally stored as `edi
 - `ownership` — authorization projection from the resource creator.
 - `share` — explicit sharing with an organization user or role.
 
-Ownership source of truth remains the tool/system row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
+Ownership source of truth remains the resource row. Ownership grants are a permission projection and should be preserved by ordinary role edits.
 
 ## Visibility and Execution Surfaces
 
 - **Tools** — list/detail, agent views, VFS, REST detail, and tool history use tool `viewer`.
-- **Systems** — list/detail, agent views, VFS, docs, credentials, and `sg system call` use system `viewer`.
-- **Execution** — running a tool requires tool `viewer` plus system `viewer` for every referenced system.
-- **Editing** — updating tools/systems requires `editor`.
-- **Runs** — visible only when the user has tool `viewer` and system `viewer` for every captured system.
+- **Connections** — usable with credential `viewer`; changing secrets, name, url, auth, or tunnel requires credential `editor`. System IDs and system knowledge are metadata, not access-controlled resources. `sg system call` needs an accessible connection only when the request uses secrets or the connection url.
+- **Execution** — running a tool requires tool `viewer` plus an accessible connection for every referenced system id: an explicit credentials id, the user's starred default, or their longest-held accessible connection.
+- **Editing** — updating a tool requires tool `editor`.
+- **Runs** — visible with tool `viewer`, limited to the member's own runs when the organization setting "members see only own runs" is on (the default). Admins see all runs.
 - **Schedules** — visibility follows current tool behavior; editing requires tool `editor`.
-- **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still checks referenced systems.
+- **MCP** — config shows configured tools; runtime registration uses tool `viewer`, and execution still needs a connection for every referenced system id.
 
 ## Multi-Role Semantics
 
 Users can have multiple roles. Resolution is union:
 
-| Layer   | Semantics                                                                  |
-| ------- | -------------------------------------------------------------------------- |
-| Tools   | If any active grant targets a tool, that grant's permission is effective   |
-| Systems | If any active grant targets a system, that grant's permission is effective |
+| Layer        | Semantics                                                                      |
+| ------------ | ------------------------------------------------------------------------------ |
+| Any resource | If any active grant targets the resource, that grant's permission is effective |
 
 Assigned roles can add access but cannot remove access granted by another role.
 
@@ -76,7 +73,7 @@ Assigned roles can add access but cannot remove access granted by another role.
 Every user has exactly one base role:
 
 - **`admin`** — built-in editor access to resources except credentials. Credentials require ownership or explicit grants. New organizations give admins no credential wildcard. Credential grants are editable. Name and description cannot be changed. Cannot be deleted.
-- **`member`** — default for org team members. New organizations seed it with wildcard `editor` grants for tools and systems. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
+- **`member`** — default for org team members. New organizations seed it with a wildcard `editor` grant for tools. Access-rule grants can be narrowed. Name and description cannot be changed. Cannot be deleted.
 - **`service_account`** — API-only users that admins create through `/v1/service-accounts`. Starts with no grants; only its grants are editable. Users cannot be switched to or from it. Service accounts can run granted tools and manage their own credential sets, but cannot log in, use MCP, or read runs.
 
 Users can also have additional custom roles on top of their base role. Custom roles are fully editable and can be created/deleted.
@@ -86,31 +83,29 @@ Users can also have additional custom roles on top of their base role. Custom ro
 Personal roles are per-user containers for ownership and user-targeted share grants.
 
 - Each user can have at most one personal role.
-- Ownership grants are added automatically when a user creates a tool or system.
+- Ownership grants are added automatically when a user creates a tool, connection, playbook, artifact, file, or project.
 - Personal role grants are unioned with the user's other roles.
 - Ordinary role edits preserve personal roles and their ownership/share grants.
 
 ## Sharing Semantics
 
-Sharing supports saved tools, systems, credentials, projects, playbooks, artifacts, and files.
+Sharing supports saved tools, connections, projects, playbooks, artifacts, and files.
 
 - Targets are organization users or roles. The admin role and personal roles cannot be role targets.
 - User-targeted shares live on personal roles; role-targeted shares live on the selected role.
 - Sharing requires resource `editor` access. Direct shares grant `viewer` or `editor` through `source: "share"`.
 - Editors can update or remove direct shares. Removing one preserves ownership, access-rule grants, and access from other roles.
-- Credential sharing and revocation require the credential owner or an admin, even when another user has credential `editor`.
-- Recipients can remove their own direct share, including credential shares, without editor access.
-- Tool sharing grants missing system `viewer` access when the actor can pass it on. Otherwise, nothing is shared.
-- Tool sharing does not share credentials. Credential sharing also grants missing viewer access to its owning system.
-- Removing a tool or credential share does not remove the required-system shares it created.
-- Sharing systems or playbooks does not cascade to their tools, systems, or credentials.
+- Connection sharing and revocation require the connection owner or an admin, even when another user has connection `editor`.
+- Recipients can remove their own direct share, including connection shares, without editor access.
+- Sharing a tool shares only the tool. The recipient still needs a connection for every system id it references.
+- Sharing playbooks does not cascade to their tools or connections.
 - Project sharing can include manageable current members when requested. It does not share future members or revoke member shares later.
 
 ## Auto-Grant On Resource Creation
 
-When a user creates a new tool or system, the backend automatically grants ownership access to the creator's personal role:
+When a user creates a new resource, the backend automatically grants ownership access to the creator's personal role:
 
 - New tool created -> `ownership` grant on `tool:<toolId>` with `editor`.
-- New system created -> `ownership` grant on `system:<systemId>` with `editor`.
+- New connection created -> `ownership` grant on `credential:<connectionId>` with `editor`.
 
 This only affects the creator's personal role, not base roles or additional custom roles.

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

@@ -96,11 +96,7 @@ Note the `cursorPath` and `stopCondition` must account for the GraphQL `data` wr
 
 ### Schema Discovery
 
-Superglue automatically introspects GraphQL schemas during documentation fetching. When a system URL contains "graphql", introspection is the first strategy tried — the full schema is fetched and stored as system documentation.
-
-Use `sg system search-docs` to query the stored schema for types, fields, and arguments before building tools. This is more reliable than manual introspection and works even when the API has introspection disabled for external callers.
-
-If the schema is not available via `sg system search-docs` (e.g. the system was created without a GraphQL URL, or introspection was blocked), test manually with `sg system call`:
+Use saved schemas or provider documentation when available. When the schema is unknown, probe the endpoint with `sg system call`:
 
 ```json
 { "query": "{ __typename }" }
@@ -126,6 +122,6 @@ When a GraphQL step fails:
 
 1. **Check GraphQL-level errors** — even 200 responses can contain `errors` in the response body. Check `sourceData.stepId.data.errors` for field-level or validation errors.
 2. **Verify the endpoint works** — use `sg system call` with `{ "query": "{ __typename }" }` to confirm connectivity and auth before debugging the query itself.
-3. **Check schema compatibility** — fields, types, and arguments change between API versions. Use `sg system search-docs` to check the auto-introspected schema first. If unavailable, use targeted `__type` queries or web search to verify the current schema.
+3. **Check schema compatibility** — fields, types, and arguments change between API versions. Check saved schemas, provider documentation, or targeted `__type` queries against the current API version.
 4. **Verify variables match the query signature** — GraphQL type mismatches (e.g. passing a string where `ID!` is expected) cause validation errors. Check that variable types in the query match what you're passing.
 5. **Check for auth scope issues** — some GraphQL APIs return partial data with `null` fields and errors when the token lacks required scopes for specific fields.

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

@@ -259,7 +259,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 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 `//`.
+- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the selected connection's `url`, exactly as stored — it may or may not end in `/`. Read `url` from `sg system connection get --system-id <systemId>` 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
@@ -273,8 +273,8 @@ When an HTTP step fails and the cause is not immediately clear:
 
 1. **Isolate endpoint vs system-level issues** — use `sg system call` to test a different endpoint on the same system. If multiple endpoints fail, the issue is likely global authentication or system configuration. If only one fails, the issue is endpoint-specific (wrong URL, missing params, incorrect method or authentication scopes).
 
-2. **Check credential scopes and system-side configuration** — a 403 or empty response often means the API key or OAuth token lacks required scopes, or the resource is restricted server-side. Use `sg system search-docs` or a web search to look up required scopes/permissions for the endpoint.
+2. **Check credential scopes and system-side configuration** — a 403 or empty response often means the API key or OAuth token lacks required scopes, or the resource is restricted server-side. Consult provider documentation or web search for the endpoint’s required scopes and permissions.
 
-3. **Verify request shape against API docs** — use `sg system search-docs` and web search to confirm the endpoint URL, required headers, query parameters, body format, and expected method. APIs change across versions. Search for the error message and the endpoint in docs and online.
+3. **Verify request shape against API docs** — consult provider documentation and web search to confirm the endpoint URL, required headers, query parameters, body format, and expected method. APIs change across versions. Search for the error message and the endpoint in docs and online.
 
 4. **Check for rate limiting** — 429 errors are retried automatically with backoff, but persistent 429s may mean the API key has hit a quota. Check API dashboard or docs for rate limit details.

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

@@ -13,7 +13,7 @@
 
 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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
 

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

@@ -13,9 +13,9 @@
 }
 ```
 
-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.
+Configure the connection URL based on the selected connection'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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 
@@ -95,7 +95,7 @@ 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), add secrets with these names to the credential:
+For on-prem SQL Servers that only accept Windows domain logins (no SQL auth), add secrets with these names to the connection:
 
 | Secret Name | Required | Notes                                                 |
 | ----------- | -------- | ----------------------------------------------------- |
@@ -113,7 +113,7 @@ Alternatively, pass the domain as a `?domain=CORP` query parameter on the URL
 
 ### Azure Active Directory Authentication
 
-For Azure AD auth, add secrets with the following names to the credential alongside the standard connection fields:
+For Azure AD auth, add secrets with the following names to the connection alongside the standard connection fields:
 
 **Entra ID User + Password** — authenticates as an Azure AD user. Requires an Azure app registration.
 

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

@@ -13,7 +13,7 @@
 
 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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 

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

@@ -13,7 +13,7 @@
 
 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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for database steps.
 

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

@@ -13,7 +13,7 @@
 
 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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for Redis steps.
 

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

@@ -13,9 +13,9 @@ 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.
+Configure the connection URL based on the selected connection'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`.
+`<<systemId_url>>` resolves to the selected connection's `url`. Use it as the full connection string when each tenant has its own host; set it with `sg system connection set --url`.
 
 `method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for file server steps.
 
@@ -63,11 +63,11 @@ Credentials are embedded in the connection URL using `<<systemId_credentialKey>>
 sftp://<<my_server_username>>:<<my_server_password>>@host/path
 ```
 
-**SFTP private key auth:** use `credentials.privateKey` and `credentials.passphrase` on the system instead of URL password placeholders. Store the private key as a credential on the system.
+**SFTP private key auth:** store `privateKey` and `passphrase` as secrets on the connection instead of URL password placeholders.
 
 **SMB domain auth:** use `domain\user` format in the URL, or store `domain` as a system credential.
 
-Only store connection credentials on the system: `host`, `port`, `username`, `password`, `privateKey`, `passphrase`, `domain` (SMB), `home_dir`. Paths and share names belong in the URL, not in credentials.
+Store these secrets on the connection: `host`, `port`, `username`, `password`, `privateKey`, `passphrase`, `domain` (SMB), `home_dir`. Paths and share names belong in the URL, not in credentials.
 
 ## File Server Runtime Details
 
@@ -158,6 +158,6 @@ When a file server step fails and the cause is not obvious:
 3. **Check path resolution** — if you get "file not found", verify the path is relative to the URL base path, not an absolute filesystem path. Use `list` on the parent directory to see what files exist.
 4. **Check permissions** — permission denied errors mean the user account lacks read/write access to the target path. Verify with the user that the account has the required grants.
 5. **Check protocol-specific issues:**
-   - **SFTP**: if the error mentions authentication, verify whether the server expects password or private key auth. If using private key, ensure `privateKey` and `passphrase` are stored as secrets in the credential.
+   - **SFTP**: if the error mentions authentication, verify whether the server expects password or private key auth. If using private key, ensure `privateKey` and `passphrase` are stored as secrets on the connection.
    - **FTP/FTPS**: if the connection fails, try switching between `ftp://` and `ftps://` — some servers require TLS, others don't support it.
    - **SMB**: verify the share name is correct (first path segment). If using domain auth, ensure the domain is included in the URL or stored as a secret. Check that the SMB port (445) is accessible.

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

@@ -36,7 +36,7 @@ sg system call --system-id netsuite \
 
 ### Login
 
-The step logs in with the system's NetSuite OAuth token, the same one the REST steps use. It runs as the user and role that connected NetSuite. The role needs the permissions **Log in using OAuth 2.0 Access Tokens**, **REST Web Services**, and **SuiteCloud Development Framework**; the standard Developer role has them. The integration record needs **REST Web Services** and **RESTlets** checked, and the sign-in needs the scopes `rest_webservices` and `restlets`. Nothing else is stored on the credential.
+The step logs in with the connection's NetSuite OAuth token, the same one the REST steps use. It runs as the user and role that connected NetSuite. The role needs the permissions **Log in using OAuth 2.0 Access Tokens**, **REST Web Services**, and **SuiteCloud Development Framework**; the standard Developer role has them. The integration record needs **REST Web Services** and **RESTlets** checked, and the sign-in needs the scopes `rest_webservices` and `restlets`. Nothing else is stored on the connection.
 
 ## Operations