@sulala/agent 0.1.6 → 0.1.8

package/context/drive.md

@@ -0,0 +1,49 @@
+---
+name: drive
+description: Use Google Drive via the Portal. When the user asks to list files, create a folder, upload/download files, or manage Drive content, use this skill with list_integrations_connections (provider drive) and run_command + curl.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📁",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Google Drive
+
+Use **list_integrations_connections** with `provider: "drive"`, then **get_connection_token** (do not curl the portal). Then call Drive with that token.
+
+1. **list_integrations_connections** with `provider: "drive"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken`.
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>` for all requests below.
+
+Add `www.googleapis.com` to **ALLOWED_CURL_HOSTS**.
+
+Base URL: `https://www.googleapis.com/drive/v3`
+
+---
+
+## List files
+
+`GET https://www.googleapis.com/drive/v3/files?pageSize=20&q=<query>` (e.g. `q='root' in parents` for root; `q=trashed=false`). Returns `files[].id`, `name`, `mimeType`.
+
+---
+
+## Create folder
+
+`POST https://www.googleapis.com/drive/v3/files` with body `{"name": "FolderName", "mimeType": "application/vnd.google-apps.folder"}`. Optional: `"parents": ["<folderId>"]`.
+
+---
+
+## Upload file (small)
+
+Use multipart: one part JSON `{"name": "filename.txt", "parents": ["<folderId>"]}`, second part file content. Or use resumable upload (see Drive API docs).
+
+---
+
+## Download file
+
+`GET https://www.googleapis.com/drive/v3/files/<fileId>?alt=media` with `Authorization: Bearer <token>` (binary response). For export of Google Docs/Sheets use `GET https://www.googleapis.com/drive/v3/files/<fileId>/export?mimeType=text/plain` (or other export type).
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Google Drive in the Portal or dashboard Integrations.

package/context/dropbox.md

@@ -0,0 +1,39 @@
+---
+name: dropbox
+description: Use Dropbox (files) via the Portal. When the user asks to list, upload, or download Dropbox files, list connections with list_integrations_connections (provider dropbox) and use run_command with curl to the Dropbox API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📁",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Dropbox
+
+1. **list_integrations_connections** with `provider: "dropbox"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>`. RPC-style endpoints use `Content-Type: application/json` and body; content endpoints use `Dropbox-API-Arg` header.
+
+Add `api.dropboxapi.com` and `content.dropboxapi.com` to **ALLOWED_CURL_HOSTS**. Official docs: https://www.dropbox.com/developers/documentation/http/documentation
+
+---
+
+## List folder
+
+- **List folder**: `POST https://api.dropboxapi.com/2/files/list_folder` with body `{"path": ""}` for root or `{"path": "/FolderName"}`. Returns `entries[].name`, `entries[].id`, `entries[].tag` (file/folder). Pagination: `cursor` in response, then `POST https://api.dropboxapi.com/2/files/list_folder/continue` with `{"cursor": "..."}`.
+
+---
+
+## Download file
+
+- **Download**: `POST https://content.dropboxapi.com/2/files/download` with header `Dropbox-API-Arg: {"path": "/path/to/file.txt"}`. No body. Response body is file content (binary). Use same `Authorization: Bearer <token>`.
+
+---
+
+## Upload file
+
+- **Upload** (small file): `POST https://content.dropboxapi.com/2/files/upload` with header `Dropbox-API-Arg: {"path": "/path/to/destination.txt", "mode": "add"}` and `Content-Type: application/octet-stream`, body = raw file bytes. `mode`: "add" (always add), "overwrite", "add" with autorename.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Dropbox in the Portal.

package/context/facebook.md

@@ -0,0 +1,47 @@
+---
+name: facebook
+description: Use Facebook (Graph API, pages) via the Portal. When the user asks to post or manage Facebook content, list connections with list_integrations_connections (provider facebook) and use run_command with curl to the Graph API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📘",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Facebook
+
+1. **list_integrations_connections** with `provider: "facebook"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** to `https://graph.facebook.com`. Use `access_token=<accessToken>` in query or `Authorization: Bearer <accessToken>` in header per endpoint.
+
+Add `graph.facebook.com` to **ALLOWED_CURL_HOSTS**. Official docs: https://developers.facebook.com/docs/graph-api
+
+---
+
+## User and pages
+
+- **Get user info**: `GET https://graph.facebook.com/me?fields=id,name,email&access_token=<token>`. Do **not** use this id as the target for posting (it is a person, not a page).
+- **Get user's pages** (required before any post): `GET https://graph.facebook.com/me/accounts?access_token=<token>`. Returns `data[].id` (page id), `data[].name`, `data[].access_token` (page token). Use these for posting.
+
+---
+
+## Post to page (required flow)
+
+**Never post to the user's ID or /me.** The user ID from `GET /me` is a person, not a page. You must use a **page** id and **page** access token from `me/accounts`. **Never use placeholders** like `your_page_id` or `<page_id>` in real API calls—Facebook will reject them. Always get real values from step 2.
+
+1. Get **user** token: `list_integrations_connections` → `get_connection_token` → `accessToken`.
+2. **Call** `GET https://graph.facebook.com/v25.0/me/accounts?access_token=<user_token>`. Response: `data[]` with `id`, `name`, `access_token` (page token). You must do this before posting; the POST needs real `id` and `access_token` from this response.
+3. Pick a page: if the user said a name (e.g. "playoutdoor"), find the item in `data` whose `name` matches (e.g. "PlayOutdoor : Tennis, Bike & Run"); otherwise use `data[0]`. Let `PAGE_ID` = that item’s `id`, `PAGE_TOKEN` = that item’s `access_token`.
+4. Post: `POST https://graph.facebook.com/v25.0/PAGE_ID/feed` with body `{"message": "Your text here", "access_token": "PAGE_TOKEN"}`. Use the actual string values for PAGE_ID and PAGE_TOKEN from step 3 (e.g. if id is `677659355438097`, the URL is `.../v25.0/677659355438097/feed`).
+
+- **Photo**: `POST https://graph.facebook.com/v25.0/PAGE_ID/photos` with the **page** token. The image must be at a **publicly reachable URL** — Facebook's servers fetch it. **URLs like http://127.0.0.1 or http://localhost do not work** (Facebook cannot reach your machine). Use a public URL (e.g. deploy the gateway or expose it via ngrok and use that base URL for uploads). When the user attaches media in chat, the message includes "[Attached media ... URLs]"; use one of those URLs only if it is public. Use **form data** (not JSON) for the photos endpoint. Example with curl: `curl -X POST "https://graph.facebook.com/v25.0/PAGE_ID/photos" -F "url=IMAGE_PUBLIC_URL" -F "caption=Optional caption" -F "access_token=PAGE_TOKEN"`. Replace PAGE_ID, IMAGE_PUBLIC_URL, and PAGE_TOKEN with real values from step 3. For multiple images, post one at a time.
+
+---
+
+## Page insights (optional)
+
+- **Page insights**: `GET https://graph.facebook.com/<page_id>/insights?metric=page_impressions&access_token=<page_token>`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Facebook in the Portal. For posting to a Page, the Facebook app must request (and the user grant) **pages_manage_posts** and **pages_read_engagement**; the token used for the POST must be the **page** access token from `me/accounts`, not the user token. If photo post fails: ensure the image URL is **public** (not 127.0.0.1/localhost), use form params (`-F`) for `/photos`, and use the page token from `me/accounts`.

package/context/fetch-form-api.md

@@ -0,0 +1,16 @@
+---
+name: fetch-form-api
+description: Fetches and returns data from a free API. Use when the user asks for specific data from a public API.
+---
+# Fetch Form API
+
+Use when the user asks for data from a free API, such as forms, weather, or any public information.
+
+## How to use
+- Invoke this skill to fetch data from available public APIs by specifying the endpoint and any necessary parameters.
+
+## Example
+- To fetch weather information, specify the weather API endpoint along with location parameters.
+
+## Limits
+- Ensure the API has a rate limit that does not exceed the allowed number of requests.

package/context/figma.md

@@ -0,0 +1,30 @@
+---
+name: figma
+description: Use Figma (files, projects) via the Portal. When the user asks about Figma files or designs, list connections with list_integrations_connections (provider figma) and use run_command with curl to the Figma API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "🎨",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Figma
+
+1. **list_integrations_connections** with `provider: "figma"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>` (or `X-Figma-Token` per Figma docs).
+
+Base URL: `https://api.figma.com/v1`. Add `api.figma.com` to **ALLOWED_CURL_HOSTS**. Official docs: https://www.figma.com/developers/api
+
+---
+
+## Files and projects
+
+- **Get file** (document structure, nodes): `GET https://api.figma.com/v1/files/<file_key>`. Returns document tree, pages, frames. `file_key` is the ID from the Figma file URL.
+- **Get file nodes** (specific nodes): `GET https://api.figma.com/v1/files/<file_key>/nodes?ids=<node_id1>,<node_id2>`.
+- **Get projects** (team): `GET https://api.figma.com/v1/teams/<team_id>/projects`. Returns `projects[].id`, `name`. Get `team_id` from user or from project response.
+- **Get project files**: `GET https://api.figma.com/v1/projects/<project_id>/files`. Returns `files[].key`, `name`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Figma in the Portal. File/project must be accessible to the connected account.

package/context/github.md

@@ -0,0 +1,58 @@
+---
+name: github
+description: Use GitHub (repos, issues, PRs, comments) via the Portal. When the user asks about repos, issues, or pull requests, list connections with list_integrations_connections (provider github) and use run_command with curl to the GitHub API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "🐙",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# GitHub
+
+1. **list_integrations_connections** with `provider: "github"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>` and `Accept: application/vnd.github.v3+json` for all requests.
+
+Base URL: `https://api.github.com`. Add `api.github.com` to **ALLOWED_CURL_HOSTS**.
+
+Official docs: https://docs.github.com/en/rest
+
+---
+
+## Repositories
+
+- **List repos** (authenticated user): `GET https://api.github.com/user/repos?per_page=20&sort=updated`. Returns `[].id`, `name`, `full_name`, `clone_url`, `private`.
+- **List repos** (org): `GET https://api.github.com/orgs/<org>/repos?per_page=20`.
+
+---
+
+## Issues
+
+- **List issues** (repo): `GET https://api.github.com/repos/<owner>/<repo>/issues?state=all&per_page=20`. Returns `[].number`, `title`, `state`, `body`, `user.login`.
+- **Create issue**: `POST https://api.github.com/repos/<owner>/<repo>/issues` with body `{"title": "Title", "body": "Description"}`. Optional: `"labels": ["bug"]`, `"assignees": ["username"]`.
+- **Get issue**: `GET https://api.github.com/repos/<owner>/<repo>/issues/<issue_number>`.
+
+---
+
+## Comments
+
+- **List comments** (on issue): `GET https://api.github.com/repos/<owner>/<repo>/issues/<issue_number>/comments`.
+- **Create comment** (on issue): `POST https://api.github.com/repos/<owner>/<repo>/issues/<issue_number>/comments` with body `{"body": "Comment text"}`.
+
+---
+
+## Pull requests
+
+- **List PRs**: `GET https://api.github.com/repos/<owner>/<repo>/pulls?state=open&per_page=20`.
+- **Create PR**: `POST https://api.github.com/repos/<owner>/<repo>/pulls` with body `{"title": "Title", "head": "<branch>", "base": "main", "body": "Description"}`. `head` is the branch with changes (e.g. `username:feature-branch` for fork).
+
+---
+
+## File content
+
+- **Get file**: `GET https://api.github.com/repos/<owner>/<repo>/contents/<path>`. Response has `content` (base64); decode to get file text. Optional: `?ref=<branch>`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect GitHub in the Portal.

package/context/gmail.md

@@ -0,0 +1,52 @@
+---
+name: gmail
+description: Use Gmail via the Portal. When the user asks to read email, send email, list messages, or archive mail, use this skill with list_integrations_connections (provider gmail) and run_command + curl.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📧",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Gmail
+
+Use **list_integrations_connections** with `provider: "gmail"`, then **get_connection_token** to get an OAuth token (do not curl the portal from run_command—use the tool). Then call Gmail with that token.
+
+**Required order:**
+1. **list_integrations_connections** with `provider: "gmail"` → get `connection_id` (e.g. from `connections[0].id`).
+2. **get_connection_token** with that `connection_id` → returns `accessToken`. This runs server-side; the agent does not curl the portal.
+3. **run_command (curl)** — call Gmail APIs with header `Authorization: Bearer <accessToken>` (the value from step 2). Do **not** use the Portal API key on Gmail URLs.
+
+If you get 401, you skipped step 2: call **get_connection_token** first, then use the returned `accessToken` in the Gmail curl.
+
+Add `gmail.googleapis.com` to **ALLOWED_CURL_HOSTS**.
+
+Base URL: `https://gmail.googleapis.com/gmail/v1`
+
+---
+
+## List messages (inbox)
+
+`GET https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=20` (optional: `q=is:unread`, `pageToken`). Returns `messages[].id`; use `threadId` if needed.
+
+---
+
+## Get message (body, subject, from)
+
+`GET https://gmail.googleapis.com/gmail/v1/users/me/messages/<messageId>?format=full` (or `format=metadata`). Decode `payload.parts[].body.data` or `payload.body.data` (base64url) for body.
+
+---
+
+## Send email
+
+Build MIME (From, To, Subject, body); base64url-encode it. `POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send` with body `{"raw": "<base64url-encoded-mime>"}`. Or use `{"raw": "<base64url>"}` where the MIME string is encoded (e.g. with a small script or base64).
+
+---
+
+## Archive message
+
+`POST https://gmail.googleapis.com/gmail/v1/users/me/messages/<messageId>/modify` with body `{"removeLabelIds": ["INBOX"]}`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Gmail in the Portal or dashboard Integrations.

package/context/google.md

@@ -0,0 +1,28 @@
+---
+name: google
+description: Google services are split by product. Use the skill that matches the request—calendar for events, gmail for email, drive for files, docs/sheets/slides for Docs/Sheets/Slides. Do not loop over one doc; pick the right skill.
+metadata:
+  {
+    "sulala": {
+      "emoji": "🔷",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Google (per-service skills)
+
+**Use one skill per product.** The Portal has separate providers; there is no single "google" provider.
+
+| User intent              | Skill to use   | Provider for list_integrations_connections |
+|--------------------------|----------------|--------------------------------------------|
+| Create event, calendar   | **calendar**   | `"calendar"`                                |
+| Email, Gmail             | **gmail**      | `"gmail"`                                   |
+| Drive files, folders     | **drive**      | `"drive"`                                   |
+| Google Docs              | **docs**       | `"docs"`                                    |
+| Google Sheets            | **sheets**     | `"sheets"`                                  |
+| Google Slides            | **slides**     | `"slides"`                                  |
+
+For "create an event at 9 PM" → use the **calendar** skill only. For "send an email" → use the **gmail** skill only. No need to load or loop over multiple Google sections.
+
+Each skill doc has the full flow: list_integrations_connections with that provider → get token from gateway → curl the API.

package/context/hellohub.md

@@ -0,0 +1,29 @@
+---
+name: hellohub
+description: hello
+version: 1.0.0
+---
+
+---
+name: hello-hub
+description: Example skill for testing install from hub. Use when the user asks for a greeting or hello.
+metadata:
+  {
+    "sulala": {
+      "requires": { "bins": [] }
+    }
+  }
+---
+
+# Hello Hub
+
+Example skill to test installing from the hub.
+
+Use when the user asks for:
+- A greeting
+- Hello from hub
+- Testing hub install
+
+## Usage
+
+Respond with a friendly greeting. No external tools required.

package/context/jira.md

@@ -0,0 +1,46 @@
+---
+name: jira
+description: Use Jira (sites, issues, transitions) via the Portal. When the user asks about Jira issues or projects, list connections with list_integrations_connections (provider jira) and use run_command with curl to the Jira API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "🔧",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Jira
+
+1. **list_integrations_connections** with `provider: "jira"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** to the user's Jira site (`https://<site>.atlassian.net` or `https://api.atlassian.com/...`). All requests: `Authorization: Bearer <accessToken>`, `Content-Type: application/json`. Add `*.atlassian.net` (or the site host) to **ALLOWED_CURL_HOSTS**.
+
+Official docs: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
+
+---
+
+## Cloud ID / Access
+
+- **Get accessible resources** (to find cloud ID): `GET https://api.atlassian.com/oauth/token/accessible-resources`. Returns `[].id` (cloudId), `[].url` (e.g. `https://site.atlassian.net`). Use cloud ID in REST v3 URLs: `https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/...`.
+
+---
+
+## Search issues
+
+- **Search**: `POST https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/search` with body `{"jql": "project = MYPROJECT ORDER BY created DESC", "maxResults": 20, "fields": ["summary", "status", "assignee"]}`. Returns `issues[].key`, `issues[].fields.summary`, `issues[].fields.status.name`. JQL examples: `assignee = currentUser()`, `status = "In Progress"`.
+
+---
+
+## Create issue
+
+- **Create**: `POST https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/issue` with body `{"fields": {"project": {"key": "PROJ"}, "summary": "Title", "issuetype": {"name": "Task"}, "description": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Description"}]}]}}}`. Get project keys from `/rest/api/3/project`; issuetypes from `/rest/api/3/issue/createmeta`.
+
+---
+
+## Transitions
+
+- **Get transitions** (for an issue): `GET https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/issue/<issueKey>/transitions`. Returns `transitions[].id`, `transitions[].name`.
+- **Transition issue**: `POST https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/issue/<issueKey>/transitions` with body `{"transition": {"id": "<transitionId>"}}`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Jira in the Portal.

package/context/linear.md

@@ -0,0 +1,40 @@
+---
+name: linear
+description: Use Linear (teams, issues) via the Portal. When the user asks about Linear teams or issues, list connections with list_integrations_connections (provider linear) and use run_command with curl to the Linear API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📋",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Linear
+
+**Creating an issue:** First run the teams query to get a real team `id` (UUID). Then POST the issue with body `{"query": "mutation ... $teamId $title $description ...", "variables": {"teamId": "<from teams>", "title": "...", "description": "..."}}`. Never embed title or description in the query string—use variables only.
+
+1. **list_integrations_connections** with `provider: "linear"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** to `POST https://api.linear.app/graphql` with `Authorization: Bearer <accessToken>`, `Content-Type: application/json`, and body `{"query": "<GraphQL>", "variables": {...}}`. Use **variables** for any user-provided text (title, description) so quotes and newlines do not break the query.
+
+Add `api.linear.app` to **ALLOWED_CURL_HOSTS**. Official docs: https://developers.linear.app/docs/graphql
+
+---
+
+## Teams
+
+- **List teams**: Query `query { teams { nodes { id name key } } }`. Returns `data.teams.nodes`.
+
+---
+
+## Issues
+
+- **List issues** (filter by team or assignee): `query { issues(first: 20, filter: { team: { key: { eq: "ENG" } } }) { nodes { id identifier title state { name } assignee { name } } } }`. Or use `filter: { assignee: { id: { eq: "<userId>" } } }`.
+
+- **Create issue** — you must do two steps. **Step 1:** Get a real team ID by sending a POST to `https://api.linear.app/graphql` with body `{"query":"query { teams { nodes { id name key } } }"}`. Use one of the returned `nodes[].id` values (UUID format like `23f232c2-7a1c-407e-8e6c-3c75bdfd0d41`). **Step 2:** Create the issue by POSTing to the same URL with a body that has **two keys only**: `query` (a mutation that uses variables, no literal title/description) and `variables` (JSON with the actual teamId, title, description). Do **not** put title or description inside the query string—that causes "Syntax Error: Unexpected }". Use this exact shape:
+  - Body: `{"query": "mutation IssueCreate($teamId: String!, $title: String!, $description: String) { issueCreate(input: { teamId: $teamId, title: $title, description: $description }) { success issue { id identifier url } } }", "variables": {"teamId": "<paste the team id from step 1>", "title": "Test Issue", "description": "Optional description"}}`
+  - The `query` string must contain only `$teamId`, `$title`, `$description`—no quoted literals for those. The `variables` object holds the real values.
+- **Update issue** (e.g. state, assignee): `mutation { issueUpdate(id: "<issueId>", input: { stateId: "<stateId>" }) { success issue { id state { name } } } }`. List states with `query { workflowStates(filter: { team: { id: { eq: "<teamId>" } } }) { nodes { id name } } }`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Linear in the Portal.

package/context/notion.md

@@ -0,0 +1,45 @@
+---
+name: notion
+description: Use Notion (search, pages, databases) via the Portal. When the user asks about Notion pages or databases, list connections with list_integrations_connections (provider notion) and use run_command with curl to the Notion API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📝",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Notion
+
+1. **list_integrations_connections** with `provider: "notion"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (do not curl the portal).
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>`, `Notion-Version: 2022-06-28`, and `Content-Type: application/json` where applicable.
+
+Base URL: `https://api.notion.com/v1`. Add `api.notion.com` to **ALLOWED_CURL_HOSTS**.
+
+Official docs: https://developers.notion.com/reference
+
+---
+
+## Search
+
+- **Search** (pages and databases): `POST https://api.notion.com/v1/search` with body `{"query": "optional search text", "filter": {"property": "object", "value": "page"}}` or `"value": "database"`. Returns `results[].id`, `url`, `object` (page/database). Omit filter to get both.
+
+---
+
+## Pages
+
+- **Get page** (content and properties): `GET https://api.notion.com/v1/pages/<page_id>`. Page ID is the UUID from a Notion URL (with hyphens).
+- **Get page content** (blocks): `GET https://api.notion.com/v1/blocks/<page_id>/children?page_size=100`. Returns block objects (paragraph, heading, etc.); `type` and `paragraph.rich_text` or similar.
+- **Create page** (under parent): `POST https://api.notion.com/v1/pages` with body `{"parent": {"page_id": "<parent_page_id>"}, "properties": {"title": {"title": [{"text": {"content": "Page title"}}]}}}`. Parent page must be shared with the integration.
+- **Update page** (e.g. title): `PATCH https://api.notion.com/v1/pages/<page_id>` with body `{"properties": {"title": {"title": [{"text": {"content": "New title"}}]}}}`.
+
+---
+
+## Databases
+
+- **Create database** (under parent page): `POST https://api.notion.com/v1/databases` with body `{"parent": {"page_id": "<parent_page_id>"}, "title": [{"text": {"content": "DB name"}}], "properties": {"Name": {"title": {}}}}`. Default "Name" property is created.
+- **Query database** (list rows): `POST https://api.notion.com/v1/databases/<database_id>/query` with body `{}` or `{"filter": {...}, "sorts": [{"property": "Name", "direction": "ascending"}]}`. Returns `results[]` (page objects with properties).
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Notion in the Portal. Pages/databases must be shared with the connected Notion integration.

package/context/portal-integrations.md

@@ -0,0 +1,42 @@
+---
+name: portal-integrations
+description: Use connected apps (Gmail, Calendar, Zoom, Slack, GitHub, etc.) via the Portal. When the user asks about email, calendar, meetings, or other integrated apps, list connections with list_integrations_connections and use run_command with curl to the gateway or provider APIs (see per-integration skills: calendar, gmail, drive, docs, sheets, slides, github, notion, slack, linear, zoom, airtable, etc.).
+metadata:
+  {
+    "sulala": {
+      "emoji": "🔌"
+    }
+  }
+---
+
+# Portal integrations
+
+The agent uses **connected apps** (Gmail, Google Calendar, Zoom, Slack, GitHub, Notion, Linear, Airtable, etc.) via **skills** and **run_command** with curl. The user connects apps in the Portal (or dashboard → Integrations); the agent gets `connection_id` from **list_integrations_connections** and performs actions by following the relevant integration skill (e.g. calendar.md, gmail.md, drive.md, github.md, slack.md) and calling **run_command** with `binary: "curl"` to the gateway or provider API.
+
+## How it works
+
+1. **User** creates an API key at the Portal and adds it in the agent (Settings → Portal API key or `PORTAL_API_KEY`). Optionally set `PORTAL_GATEWAY_URL`.
+2. **User** connects apps in the Portal (or dashboard Integrations): Gmail, Calendar, Zoom, Slack, etc.
+3. **Agent** uses:
+   - **list_integrations_connections** — returns `connection_id` and `provider` for each connected app. Call with optional `provider` to filter (e.g. `"calendar"`, `"gmail"`, `"slack"`, `"github"`).
+   - **get_connection_token** — call with `connection_id` to get an OAuth `accessToken`. Use this before each integration API call; the agent does not curl the portal from run_command.
+   - **run_command** with **curl** — use the `accessToken` from get_connection_token in the `Authorization: Bearer <accessToken>` header when curling the provider API (Gmail, Calendar, GitHub, Slack, etc.), as documented in each integration skill.
+
+Integration behavior is **skill-driven**: use **list_integrations_connections** for OAuth apps (calendar, gmail, drive, github, slack, linear, etc.) and the instructions in the per-integration skills. **Stripe and Discord are not OAuth**—they are "channels" configured in **Settings → Channels** (API key / bot token). Do not use list_integrations_connections for Stripe or Discord; use **stripe_list_customers** and **discord_list_guilds** / **discord_send_message** instead. See stripe.md and discord.md.
+
+## When to use
+
+- User asks to **create a calendar event**, read/send email, check calendar, list or create Zoom meetings, post in Slack, list GitHub repos/issues, query Notion, etc. For calendar events, always use the **calendar** skill (provider `calendar`) and the Calendar API via run_command + curl; do not use Apple Calendar, osascript, or local calendar apps.
+- First call **list_integrations_connections** (optionally with `provider`, e.g. `calendar` for events), then follow the relevant integration skill and use **run_command** with curl as documented there.
+
+## Requirements
+
+- **PORTAL_GATEWAY_URL** and **PORTAL_API_KEY** must be set so the agent can list connections and get OAuth tokens. The agent loads them from **`~/.sulala/.env`** (e.g. when saved via dashboard Settings); you do not need them in the agent project `.env`. If both exist, the agent project `.env` overrides. Create the API key in the Portal → API Keys. Example in `~/.sulala/.env`: `PORTAL_GATEWAY_URL=https://portal.sulala.ai/api/gateway`, `PORTAL_API_KEY=<your key>`.
+- The user must have connected the relevant app in the Portal before the agent can use it.
+- Add required hosts to **ALLOWED_CURL_HOSTS** (e.g. api.github.com, slack.com, www.googleapis.com) as documented in each integration skill.
+
+## Notes
+
+- Connection count and subscription limits are enforced by the Portal; the agent only sees connections the user has already connected.
+- If **list_integrations_connections** returns an error like "Portal not configured", prompt the user to add a Portal API key in Settings or at the Portal.
+- For OAuth-backed actions, the Portal (or gateway) may expose action endpoints (e.g. `POST /api/gateway/actions/gmail/send`) that skills document for curl; until then, skills document calling the gateway for a token and then the provider API directly.

package/context/post-to-x.md

@@ -0,0 +1,50 @@
+---
+name: post-to-x
+description: >
+  Posts a tweet to X (formerly Twitter) using OAuth 1.0a user authentication.
+  Use this skill when the user asks to tweet, post to X/Twitter, or share an update on X.
+metadata:
+  {
+    "sulala": {
+      "requires": {
+        "bins": ["python3"],
+        "env": [
+          "X_API_KEY",
+          "X_API_SECRET",
+          "X_ACCESS_TOKEN",
+          "X_ACCESS_TOKEN_SECRET"
+        ]
+      },
+      "primaryEnv": "X_ACCESS_TOKEN",
+      "capabilities": ["write", "social", "automation"]
+    }
+  }
+---
+
+# Post to X (Twitter)
+
+This skill posts a tweet to **:contentReference[oaicite:0]{index=0}** using **OAuth 1.0a (User Context)** authentication.
+
+⚠️ **Important**
+- App-only Bearer Tokens **cannot** post tweets.
+- This skill requires **user-level OAuth 1.0a credentials** with **Read & Write** permissions.
+
+---
+
+## When to Use
+Use this skill when the user asks to:
+- Post a tweet
+- Share content on X
+- Announce something on Twitter/X
+- Publish automated updates
+
+---
+
+## Requirements
+
+### Environment Variables
+```env
+X_API_KEY=your_consumer_key
+X_API_SECRET=your_consumer_secret
+X_ACCESS_TOKEN=your_access_token
+X_ACCESS_TOKEN_SECRET=your_access_token_secret

package/context/sheets.md

@@ -0,0 +1,47 @@
+---
+name: sheets
+description: Use Google Sheets via the Portal. When the user asks to list spreadsheets, read or append rows, or edit Sheets, use this skill with list_integrations_connections (provider sheets) and run_command + curl.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📊",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Google Sheets
+
+Use **list_integrations_connections** with `provider: "sheets"`, then **get_connection_token** (do not curl the portal). Then call the API with that token.
+
+1. **list_integrations_connections** with `provider: "sheets"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken`.
+3. **run_command (curl)** with `Authorization: Bearer <accessToken>` for all requests.
+
+Add `www.googleapis.com` and `sheets.googleapis.com` to **ALLOWED_CURL_HOSTS**.
+
+---
+
+## List spreadsheets
+
+List via Drive API (mimeType `application/vnd.google-apps.spreadsheet`).
+
+---
+
+## Read range
+
+`GET https://sheets.googleapis.com/v4/spreadsheets/<spreadsheetId>/values/<range>`. Example range: `Sheet1!A1:D10`.
+
+---
+
+## Append rows
+
+`POST https://sheets.googleapis.com/v4/spreadsheets/<spreadsheetId>/values/<range>:append?valueInputOption=USER_ENTERED` with body `{"values": [[ "cell1", "cell2" ], [ "row2col1", "row2col2" ]]}`.
+
+---
+
+## Update range
+
+`PUT https://sheets.googleapis.com/v4/spreadsheets/<spreadsheetId>/values/<range>?valueInputOption=USER_ENTERED` with body `{"values": [[...]]}`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Google Sheets in the Portal or dashboard Integrations.