@sulala/agent 0.1.5 → 0.1.7

package/README.md

@@ -25,7 +25,7 @@ sulala onboard
 sulala onboard --install-daemon
 ```
 
-Then open http://127.0.0.1:3000 (dashboard and API). Add API keys at http://127.0.0.1:3000/onboard if needed.
+Then open http://127.0.0.1:3000 (dashboard and API). **Default LLM is Ollama** (local, no API key). On first run, if Ollama is not installed, the app will start the official installer for your OS (Mac/Linux/Windows). You can optionally add API keys at http://127.0.0.1:3000/onboard to use OpenAI, Claude, Gemini, or OpenRouter instead.
 
 **Or run from source (clone this repo):**
 
@@ -90,7 +90,7 @@ Set `GATEWAY_URL` and optionally `GATEWAY_API_KEY` when using gateway commands.
 
 **AI models:** Supported providers: OpenAI (e.g. gpt-5.2, gpt-5-mini, gpt-4o-mini), OpenRouter (one key for many models, e.g. openai/gpt-5.2, anthropic/claude-sonnet-4), Claude (Opus 4.6, Sonnet 4.6, Haiku 4.5), Gemini (2.5 Flash/Pro, 3.1 Pro), Ollama (local). See [docs/MODELS.md](docs/MODELS.md) for model IDs and env vars (`AI_*_DEFAULT_MODEL`, `OPENROUTER_API_KEY`, `GOOGLE_GEMINI_API_KEY`).
 
-**Config:** Watched folders can be set in `.env` (`WATCH_FOLDERS`) or in `config/watched.json` (array `folders`); both are merged. Optional gateway auth via `GATEWAY_API_KEY`; webhooks via `WEBHOOK_URL` or `WEBHOOK_URLS` and optional `WEBHOOK_SECRET`. AI: set `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, and/or use Ollama (`OLLAMA_BASE_URL`, default `http://localhost:11434`). Optional rate limit: `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`. See `.env.example`.
+**Config:** Watched folders can be set in `.env` (`WATCH_FOLDERS`) or in `config/watched.json` (array `folders`); both are merged. Optional gateway auth via `GATEWAY_API_KEY`; webhooks via `WEBHOOK_URL` or `WEBHOOK_URLS` and optional `WEBHOOK_SECRET`. AI: default is **Ollama** (no key; installs automatically if missing). Override with `AI_DEFAULT_PROVIDER=openai` (or `claude`, `gemini`, `openrouter`) and set the corresponding API keys. Optional: `OLLAMA_BASE_URL` (default `http://localhost:11434`). Optional rate limit: `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`. See `.env.example`.
 
 **Docker:** Build and run with dashboard served from the gateway:
 ```bash
@@ -133,3 +133,4 @@ sulala_agent/
 ## License
 
 MIT
+# agent

package/context/airtable.md

@@ -0,0 +1,35 @@
+---
+name: airtable
+description: Use Airtable (bases, records) via the Portal. When the user asks about Airtable bases or records, list connections with list_integrations_connections (provider airtable) and use run_command with curl to the Airtable API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📊",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Airtable
+
+1. **list_integrations_connections** with `provider: "airtable"` → 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 `Content-Type: application/json`.
+
+Airtable API uses **base ID** and **table name or ID**. Add `api.airtable.com` to **ALLOWED_CURL_HOSTS**. Official docs: https://airtable.com/developers/web/api/introduction
+
+---
+
+## Bases and tables
+
+- **List bases**: `GET https://api.airtable.com/v0/meta/bases`. Returns `bases[].id`, `bases[].name`. Use base `id` in table URLs.
+- **List tables** (schema) in a base: `GET https://api.airtable.com/v0/meta/bases/<baseId>/tables`. Returns table names and field definitions.
+
+---
+
+## Records
+
+- **List records** (one table): `GET https://api.airtable.com/v0/<baseId>/<tableNameOrId>?maxRecords=20`. Optional: `?filterByFormula=<formula>`, `?sort[0][field]=Name`. Returns `records[].id`, `records[].fields`.
+- **Create record**: `POST https://api.airtable.com/v0/<baseId>/<tableNameOrId>` with body `{"fields": {"Name": "Value", "OtherField": "Value"}}`. Field names must match the table schema.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Airtable in the Portal. Base must be shared with the connected account.

package/context/asana.md

@@ -0,0 +1,37 @@
+---
+name: asana
+description: Use Asana (workspaces, projects, tasks) via the Portal. When the user asks about Asana tasks or projects, list connections with list_integrations_connections (provider asana) and use run_command with curl to the Asana API or gateway.
+metadata:
+  {
+    "sulala": {
+      "emoji": "✅",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Asana
+
+1. **list_integrations_connections** with `provider: "asana"` → 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 `Content-Type: application/json`.
+
+Base URL: `https://app.asana.com/api/1.0`. Add `app.asana.com` to **ALLOWED_CURL_HOSTS**. Official docs: https://developers.asana.com/reference/rest-api-reference
+
+---
+
+## Workspaces and projects
+
+- **List workspaces**: `GET https://app.asana.com/api/1.0/workspaces`. Returns `data[].gid`, `data[].name`.
+- **List projects** (in workspace): `GET https://app.asana.com/api/1.0/workspaces/<workspace_gid>/projects`. Returns `data[].gid`, `data[].name`.
+
+---
+
+## Tasks
+
+- **List tasks** (in project): `GET https://app.asana.com/api/1.0/projects/<project_gid>/tasks?opt_fields=name,completed,due_on,notes`. Returns `data[].gid`, `data[].name`, etc. Pagination: `offset`, `limit`.
+- **Create task**: `POST https://app.asana.com/api/1.0/tasks` with header `Content-Type: application/json` and body `{"data": {"name": "Task title", "projects": ["<project_gid>"]}}`. The `projects` value must be an array of one or more project GID **strings** from `GET /workspaces/<workspace_gid>/projects` (e.g. `["1213334948480995"]`). Do **not** send `workspace` when sending `projects`—the API will error. Optional in `data`: `"notes": "Description"`, `"due_on": "YYYY-MM-DD"`. Flow: (1) GET `/workspaces` → pick a workspace `gid`, (2) GET `/workspaces/<workspace_gid>/projects` → pick a project `gid`, (3) POST `/tasks` with `{"data": {"name": "fix bug today", "projects": ["<project_gid>"]}}`.
+- **Get task**: `GET https://app.asana.com/api/1.0/tasks/<task_gid>?opt_fields=name,completed,notes,due_on,projects`.
+- **Update task** (mark complete, etc.): `PUT https://app.asana.com/api/1.0/tasks/<task_gid>` with body `{"data": {"completed": true}}` or `{"data": {"name": "New name"}}`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Asana in the Portal.

package/context/bluesky.md

@@ -1,111 +1,46 @@
 ---
 name: bluesky
-description: Post to Bluesky (AT Protocol). Use when the user asks to post a tweet/thread to Bluesky, share content on Bluesky, or post news/headlines from a source (URL or text) to Bluesky.
-homepage: https://bsky.app
+description: Post to Bluesky (AT Protocol). Use when the user asks to post to Bluesky or share content on Bluesky. Use either (A) Portal OAuth connection and the Bluesky proxy, or (B) app password from skill config (BSKY_HANDLE, BSKY_APP_PASSWORD).
 metadata:
   {
     "sulala": {
       "emoji": "🦋",
-      "requires": { "bins": ["curl", "python3", "sh"], "env": ["BSKY_HANDLE", "BSKY_APP_PASSWORD"] },
-      "primaryEnv": "BSKY_APP_PASSWORD"
+      "requires": { "bins": ["curl"] }
     }
   }
 ---
 
-# Bluesky Posting
+# Bluesky
 
-Post to Bluesky via the AT Protocol. Use **run_command** with `curl`, `python3`, and `sh`. Add `curl`, `python3`, and `sh` to ALLOWED_BINARIES.
+Two ways to post:
 
-Requires `BSKY_HANDLE` (e.g. `your.bsky.social`) and `BSKY_APP_PASSWORD` (app password from bsky.app → Settings → App Passwords). Set them in `.env` or in the skill config (`~/.sulala/config.json` or `.sulala/config.json` in the project; see Skill config in the dashboard). Config is re-read when the file changes; enable/disable takes effect without restart.
+## (A) Portal OAuth (recommended)
 
-**IMPORTANT:** `run_command` does not run a shell — `$BSKY_HANDLE` and `$BSKY_APP_PASSWORD` will not expand if you call curl directly. Always use `binary: "sh"` and `args: ["-c", "curl ... $BSKY_HANDLE ... $BSKY_APP_PASSWORD ..."]` so the env vars expand.
+1. **list_integrations_connections** with `provider: "bluesky"` → get `connection_id`.
+2. **bluesky_post** with that `connection_id` and the post text (max 300 characters).
 
-## When to Use
+Use the **bluesky_post** tool for posting. Do not use run_command (curl) for Bluesky—the correct endpoint is the portal gateway bsky-request, and the tool calls it for you.
 
-- "Post this to Bluesky"
-- "Share [content] on Bluesky"
-- "Post news from [URL] to Bluesky"
-- "Post a headline about [topic]"
+## (B) App password (skill config)
 
-## Post Flow (non-interactive)
+Set **BSKY_HANDLE** and **BSKY_APP_PASSWORD** (from bsky.app → Settings → App Passwords) in Skills → Bluesky config.
 
-### 1. Ensure credentials
+1. **Create session** to get access token:
+   ```bash
+   curl -s -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" \
+     -H "Content-Type: application/json" \
+     -d '{"identifier":"$BSKY_HANDLE","password":"$BSKY_APP_PASSWORD"}'
+   ```
+   Response has `accessJwt` and `did`.
 
-```
-BSKY_HANDLE="${BSKY_HANDLE:?Set BSKY_HANDLE}"
-BSKY_APP_PASSWORD="${BSKY_APP_PASSWORD:?Set BSKY_APP_PASSWORD}"
-```
+2. **Create post** (use the JWT and did from step 1):
+   ```bash
+   curl -s -X POST "https://bsky.social/xrpc/com.atproto.repo.createRecord" \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer <accessJwt>" \
+     -d '{"repo":"<did>","collection":"app.bsky.feed.post","record":{"$type":"app.bsky.feed.post","text":"<post text>","createdAt":"<ISO8601>"}}'
+   ```
 
-If empty, read from Sulala config:
+Add `bsky.social` to **ALLOWED_CURL_HOSTS**. Optional: **BSKY_PDS** (default https://bsky.social) for a custom PDS.
 
-```
-CONFIG_PATH="${SULALA_CONFIG_PATH:-$HOME/.sulala/config.json}"
-# If using workspace config, use: CONFIG_PATH=".sulala/config.json" (when run from project root)
-BSKY_HANDLE=$(cat "$CONFIG_PATH" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); e=d.get('skills',{}).get('entries',{}).get('bluesky',{}); print(e.get('handle','') or e.get('apiKey',''))" 2>/dev/null)
-BSKY_APP_PASSWORD=$(cat "$CONFIG_PATH" 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); e=d.get('skills',{}).get('entries',{}).get('bluesky',{}); print(e.get('apiKey','') or e.get('password',''))" 2>/dev/null)
-```
-
-(Config may use `handle` + `apiKey` for Bluesky. Adjust field names if your config differs.)
-
-### 2. Create session (login)
-
-**Use `run_command` with `binary: "sh"` and `args: ["-c", "..."]`** so `$BSKY_HANDLE` and `$BSKY_APP_PASSWORD` expand from the environment. Do NOT call curl directly.
-
-```bash
-sh -c 'SESSION=$(curl -s -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" -H "Content-Type: application/json" -d "{\"identifier\": \"$BSKY_HANDLE\", \"password\": \"$BSKY_APP_PASSWORD\"}"); echo "$SESSION"'
-```
-
-Then parse the JSON output with `python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('accessJwt',''), d.get('did',''))"` to get `ACCESS_TOKEN` and `DID`.
-
-If the session response contains `"error"` or `"AuthenticationRequired"`, report: "Bluesky login failed. Check BSKY_HANDLE and BSKY_APP_PASSWORD in .env."
-
-### 3. Create post
-
-Text must be JSON-escaped. Use python to build the payload. **Use `run_command` with `binary: "sh"`** so `$ACCESS_TOKEN`, `$DID`, and other vars expand.
-
-Run a single `sh -c` that chains steps 2 and 3 so SESSION, ACCESS_TOKEN, DID persist in the same shell:
-
-```bash
-sh -c '
-  SESSION=$(curl -s -X POST "https://bsky.social/xrpc/com.atproto.server.createSession" \
-    -H "Content-Type: application/json" \
-    -d "{\"identifier\": \"$BSKY_HANDLE\", \"password\": \"$BSKY_APP_PASSWORD\"}");
-  ACCESS_TOKEN=$(echo "$SESSION" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get(\"accessJwt\",\"\"))");
-  DID=$(echo "$SESSION" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get(\"did\",\"\"))");
-  if [ -z "$ACCESS_TOKEN" ]; then echo "Login failed"; exit 1; fi;
-  POST_TEXT="Your post content here";
-  POST_JSON=$(python3 -c "import sys,json; print(json.dumps(sys.argv[1]))" "$POST_TEXT");
-  NOW=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z");
-  curl -s -X POST "https://bsky.social/xrpc/com.atproto.repo.createRecord" \
-    -H "Authorization: Bearer $ACCESS_TOKEN" \
-    -H "Content-Type: application/json" \
-    -d "{\"repo\": \"$DID\", \"collection\": \"app.bsky.feed.post\", \"record\": {\"\\$type\": \"app.bsky.feed.post\", \"text\": $POST_JSON, \"createdAt\": \"$NOW\"}}"
-'
-```
-
-Replace `Your post content here` with the user's post text.
-
-If the response contains `"uri"`, the post succeeded. Otherwise report the error.
-
-## Posting from a news source
-
-When the user wants to post **news** or **content from a URL**:
-
-1. **Fetch the content** (e.g. with `curl -s <URL>` or read a file).
-2. **Summarize** if the content is long — Bluesky posts are max 300 characters. Write a short headline or summary.
-3. **Post** using the flow above. Optionally append the source URL if it fits within 300 chars.
-
-Example for "post news from https://example.com/article":
-- Fetch the page, extract title/lead.
-- Build post: "Headline here — https://example.com/article"
-- Post via the createRecord flow above.
-
-## Character limit
-
-Bluesky posts are limited to 300 characters. If the user's text or your summary exceeds that, truncate or split into multiple posts (thread). For a thread, create each post separately; the API does not natively support threads — you would need to reference the previous post's URI if linking them (advanced).
-
-## Notes
-
-- Use an **app password**, not the main account password. Create at bsky.app → Settings → App Passwords.
-- `bsky.social` is the default PDS; custom PDS users would need a different host.
-- Do not embed real credentials in the skill or in replies — use env or config.
+Official docs: https://docs.bsky.app/docs/api/atproto/

package/context/calendar.md

@@ -0,0 +1,63 @@
+---
+name: calendar
+description: Use Google Calendar via the Portal. When the user asks to create a calendar event, add to calendar, list events, or check calendar, use this skill with list_integrations_connections (provider calendar) and run_command + curl. Do not use Apple Calendar, osascript, or local calendar apps—use Google Calendar via the Portal.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📅",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Google Calendar
+
+Use **list_integrations_connections** with `provider: "calendar"`, then **get_connection_token** to get an OAuth token (do not curl the portal from run_command—use the tool). Then call Calendar with that token.
+
+1. **list_integrations_connections** with `provider: "calendar"` → get `connection_id`.
+2. **get_connection_token** with that `connection_id` → returns `accessToken` (runs server-side).
+3. **run_command (curl)** — call Calendar APIs with `Authorization: Bearer <accessToken>` for all requests below.
+
+Add `www.googleapis.com` to **ALLOWED_CURL_HOSTS**.
+
+Base URL: `https://www.googleapis.com/calendar/v3`
+
+---
+
+## List calendars
+
+`GET https://www.googleapis.com/calendar/v3/users/me/calendarList`. Use `items[].id` (e.g. `primary`) for listing events.
+
+---
+
+## List events
+
+`GET https://www.googleapis.com/calendar/v3/calendars/<calendarId>/events?timeMin=<ISO8601>&timeMax=<ISO8601>&maxResults=20&singleEvents=true`. `calendarId` is often `primary`.
+
+---
+
+## Create event
+
+**Use this for all "create a calendar event" or "add to calendar" requests.**
+
+`POST https://www.googleapis.com/calendar/v3/calendars/primary/events` with `Content-Type: application/json`, body:
+
+`{"summary": "Event title", "description": "Optional description", "start": {"dateTime": "2025-03-04T21:00:00", "timeZone": "America/New_York"}, "end": {"dateTime": "2025-03-04T21:30:00", "timeZone": "America/New_York"}}`
+
+- Example for "gym at 9 PM" today: use today's date, start 21:00, end 21:30 (or 22:00) in the user's timezone.
+- All-day: use `"start": {"date": "2025-03-15"}`, `"end": {"date": "2025-03-16"}`.
+- Times in ISO8601 with timezone (e.g. `America/New_York` or `UTC`).
+
+---
+
+## Update event
+
+`PUT https://www.googleapis.com/calendar/v3/calendars/<calendarId>/events/<eventId>` with same body shape as create.
+
+---
+
+## Delete event
+
+`DELETE https://www.googleapis.com/calendar/v3/calendars/<calendarId>/events/<eventId>`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Google Calendar in the Portal or dashboard Integrations.

package/context/country-info.md

@@ -0,0 +1,13 @@
+---
+name: country-info
+description: Provides small info about various countries. Use when the user asks for information about a specific country.
+---
+# Country Info
+
+Use when the user asks for small information about a country, such as facts, culture, and geography.
+
+## How to use
+- Ask for specific details about a country (e.g., "Tell me about Canada").
+
+## Limits
+- The information provided is brief and may not cover all aspects of the country.

package/context/create-skill.md

@@ -0,0 +1,128 @@
+---
+name: create-skill
+description: Create a new Sulala skill when the user asks for one. Use write_file to create the .md file. Use when the user asks to create, add, or write a skill.
+---
+
+# Create Sulala Skill
+
+When the user asks to create a skill (e.g. "create a skill for X", "add a skill that does Y"), create it using **write_file**. Infer the skill from the request; ask only if critical details are missing.
+
+## Skill format
+
+Every Sulala skill is a `.md` file with YAML frontmatter and a markdown body:
+
+```markdown
+---
+name: slug-or-name
+description: One-line summary of when to use this skill. Include trigger terms.
+---
+# Skill Title
+
+Use when the user asks for X, Y, or Z.
+
+## How to use
+- Commands, steps, or run_command examples
+## Limits
+- What not to do
+```
+
+**Required frontmatter:** `name` (slug, lowercase-hyphens), `description` (third person, includes WHAT and WHEN).
+
+**Required when the skill uses run_command or external APIs:** `metadata` with `sulala.requires`:
+- **bins** — list of CLI tools (e.g. `["curl", "jq"]`). Add these to ALLOWED_BINARIES. Always include if the skill uses run_command.
+- **env** — list of required env var names for API keys (e.g. `["TMDB_ACCESS_TOKEN"]`). Users configure these in Skills config.
+
+```yaml
+metadata:
+  {
+    "sulala": {
+      "requires": {
+        "bins": ["curl"],
+        "env": ["TMDB_ACCESS_TOKEN"]
+      }
+    }
+  }
+```
+
+## Where to write
+
+Use the **SKILL.md flow** (direct skill directory, not packaged .skill):
+
+1. **Use the path from the Workspace section:** In "## Context" → **## Workspace**, the prompt gives **Your skill output directory**. Use that path with write_file: `<that-directory>/<slug>/SKILL.md`. It is already resolved for the current OS. Do **not** use `~` or `$HOME`; the tool does not expand them and would create a literal folder under the project.
+2. Add `SKILL.md` with YAML frontmatter (`name`, `description`) and instructions.
+3. Add any `scripts/`, `references/`, or `assets/` under that folder if needed.
+4. Do **not** create skills under the project folder (e.g. `context/`) — they will be overwritten on project updates.
+
+If write_file cannot write to the path from the Workspace section (e.g. permission or workspace root restriction), tell the user: "Create the skill at [that path], then refresh skills or restart the gateway."
+
+## Steps
+
+1. Infer purpose and name from the user's request.
+2. Draft frontmatter (name, description) and body (when to use, how to use, limits).
+3. Call **write_file** with `path` = the skill output directory from **## Workspace** + `/<slug>/SKILL.md` (e.g. `/Users/you/.sulala/workspace/skills/<slug>/SKILL.md`). Create the directory if needed.
+4. Confirm: "Created skill at [path]. Refresh skills or restart the gateway to load it."
+
+## Example (API skill with metadata)
+
+User: "Create a skill that fetches movie data from TMDB"
+
+Include **metadata** with `bins` (curl) and `env` (API key). Use write_file with the path from **## Workspace** + `/fetch-movie/SKILL.md`:
+
+```markdown
+---
+name: fetch-movie
+description: Fetch movies using TMDB API via curl. Use when the user asks for movie details or to search movies by title.
+metadata:
+  {
+    "sulala": {
+      "requires": {
+        "bins": ["curl"],
+        "env": ["TMDB_ACCESS_TOKEN"]
+      }
+    }
+  }
+---
+
+# Fetch Movie
+
+Use **run_command** with `curl` to get movie data from The Movie Database (TMDB) API. Add `curl` to ALLOWED_BINARIES. Store your TMDB API token in Skills config as `TMDB_ACCESS_TOKEN`.
+
+## TMDB Search API
+
+- **Search:** `curl -s -H "Authorization: Bearer $TMDB_ACCESS_TOKEN" "https://api.themoviedb.org/3/search/movie?query=QUERY"`
+
+## Limits
+
+- Do not expose the token in responses. Use the env var in run_command.
+```
+
+## Example (stock price)
+
+User: "Create a skill that fetches stock prices"
+
+Use write_file with the path from **## Workspace** + `/stock-price/SKILL.md`:
+
+```markdown
+---
+name: stock-price
+description: Fetches stock prices via API. Use when the user asks for stock quotes, share price, or market data.
+---
+
+# Stock Price
+
+Use **run_command** with `curl` to call a stock API. Add `curl` to ALLOWED_BINARIES.
+
+## Alpha Vantage (requires API key)
+
+    curl -s "https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol=AAPL&apikey=$ALPHA_VANTAGE_API_KEY"
+
+## Limits
+
+- Do not share API keys in responses.
+```
+
+## Tips
+
+- Description: third person, specific, include trigger terms. Example: "Fetches weather for a city. Use when the user asks for weather, temperature, or forecast."
+- Body: concise; if the skill uses run_command, say which binaries and add to ALLOWED_BINARIES.
+- Slug: lowercase, hyphens only (e.g. `my-new-skill`).

package/context/discord.md

@@ -0,0 +1,30 @@
+---
+name: discord
+description: Use Discord (servers, channels, send messages) via Settings → Channels. Do not use list_integrations_connections for Discord—it only lists OAuth apps. Use discord_list_guilds, discord_list_channels, and discord_send_message (token from Settings → Channels).
+metadata:
+  {
+    "sulala": {
+      "emoji": "🎮",
+      "requires": { "env": ["DISCORD_BOT_TOKEN"] }
+    }
+  }
+---
+
+# Discord
+
+Discord is configured in **Settings → Channels (Discord)** or via **DISCORD_BOT_TOKEN** in the agent env. **Do not call list_integrations_connections for Discord**—that tool only returns OAuth connections (Gmail, Slack, etc.). Discord uses a bot token, not OAuth.
+
+Use the dedicated tools (they use the token from Settings):
+- **discord_list_guilds** — list servers (guilds) the bot is in. Returns guild id and name.
+- **discord_list_channels** — list channels in a guild. Requires guild_id from discord_list_guilds. Returns channel id, name, type (0=text, 2=voice, 4=category).
+- **discord_send_message** — send a message to a channel. Requires channel_id and content (max 2000 chars).
+
+---
+
+## Flow
+
+1. **discord_list_guilds** — get server (guild) ids and names.
+2. **discord_list_channels** with `guild_id` — get channel ids (type 0 = text channel).
+3. **discord_send_message** with `channel_id` and `content` — send the message.
+
+Requirements: Bot must be added to the server and have permissions to read channels and send messages.

package/context/docs.md

@@ -0,0 +1,29 @@
+---
+name: docs
+description: Use Google Docs via the Portal. When the user asks to list, create, or read Google Docs, use this skill with list_integrations_connections (provider docs) and run_command + curl.
+metadata:
+  {
+    "sulala": {
+      "emoji": "📄",
+      "requires": { "bins": ["curl"] }
+    }
+  }
+---
+
+# Google Docs
+
+Use **list_integrations_connections** with `provider: "docs"`, then **get_connection_token** (do not curl the portal). Then call the API with that token.
+
+1. **list_integrations_connections** with `provider: "docs"` → 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` to **ALLOWED_CURL_HOSTS**.
+
+---
+
+## List / create / read
+
+List and create Docs via the Drive API (mimeType `application/vnd.google-apps.document`). Export to read: `GET https://www.googleapis.com/drive/v3/files/<id>/export?mimeType=text/plain` with `Authorization: Bearer <accessToken>`.
+
+Requirements: **PORTAL_GATEWAY_URL**, **PORTAL_API_KEY**; user must connect Google Docs in the Portal or dashboard Integrations.

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`.