@sulala/agent 0.1.6 → 0.1.8

package/README.md

@@ -2,18 +2,27 @@
 
 A local-first platform that combines **file monitoring**, **task scheduling**, **AI orchestration**, and a **plugin system**. Runs on `127.0.0.1` and stays on your machine.
 
+## Contents
+
+- [Architecture](#architecture-high-level)
+- [Quick start](#quick-start)
+- [Hub & integrations](#hub--integrations)
+- [Requirements](#requirements)
+- [Project layout](#project-layout)
+- [Security](#security)
+
 ## Architecture (high level)
 
 | Layer | Role |
 |-------|------|
-| **Gateway** | REST + WebSocket API on `localhost:3000`; auth and request handling |
+| **Gateway** | REST + WebSocket API on `localhost:2026`; auth and request handling |
 | **File watcher** | Real-time folder watch (add/change/delete) → event triggers |
 | **Task scheduler** | Cron-like scheduling + queue with retries and failure handling |
 | **AI orchestration** | Single interface to multiple providers (OpenAI, OpenRouter, Claude, Gemini, Ollama); routing and rate limits |
 | **Plugins** | Scripts and integrations that hook into events, tasks, and AI |
 | **Persistence** | SQLite for tasks, file state, logs, and AI results |
 
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and the project diagram for full layout.
+See [docs/architecture.md](docs/architecture.md) and the project diagram for full layout.
 
 ## Quick start
 
@@ -25,7 +34,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:2026 (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:2026/onboard to use OpenAI, Claude, Gemini, or OpenRouter instead.
 
 **Or run from source (clone this repo):**
 
@@ -40,21 +49,12 @@ cp .env.example .env
 npm start
 ```
 
-**Development:** `npm run dev` runs the app with `tsx watch` (restarts on file changes). For a production build: `npm run build` then `node dist/index.js` (or run the gateway with `node dist/gateway/server.js`). Run tests with `npm test` and lint with `npm run lint`.
+**Development:** `npm run dev` runs with `tsx watch` (restarts on file changes). Production: `npm run build` then `node dist/index.js`. Tests: `npm test`; lint: `npm run lint`.
 
 **Dashboard (React + Vite + shadcn/ui):**
 
-- **Dev:** run the UI on its own port (e.g. 5173) while the gateway runs on 3000:
-  ```bash
-  npm run dashboard
-  ```
-  Then open the URL Vite prints (e.g. http://localhost:5173). Set `VITE_GATEWAY_URL=http://127.0.0.1:3000` in `dashboard/.env` if the API is on another host.
-- **Production:** build and serve from the gateway (one origin):
-  ```bash
-  npm run dashboard:build
-  npm start
-  ```
-  Then open http://127.0.0.1:3000 — the gateway serves the built dashboard and the API.
+- **Dev:** `npm run dashboard` — UI on its own port (e.g. 5173); gateway on 2026. Set `VITE_GATEWAY_URL=http://127.0.0.1:2026` in `dashboard/.env` if needed.
+- **Production:** `npm run dashboard:build` then `npm start` — gateway serves the built dashboard and API at http://127.0.0.1:2026.
 
 **CLI** (from project root):
 
@@ -74,29 +74,44 @@ sulala skill update
 sulala skill uninstall apple-notes [--global]
 ```
 
-**Skill commands:** `sulala skill list` lists registry skills. `sulala skill install <slug> [--global]` installs to workspace (default) or managed dir (`~/.sulala/skills`). `sulala skill update` refreshes installed skills from the registry. `sulala skill uninstall <slug> [--global]`. `sulala init [dir]` creates config/context/registry and copies `.env.example` → `.env` in a directory.
+**Skill commands:**
+
+- `sulala skill list` — list registry skills
+- `sulala skill install <slug> [--global]` — install to workspace (default) or `~/.sulala/skills`
+- `sulala skill update` — refresh installed skills from the registry
+- `sulala skill uninstall <slug> [--global]` — remove a skill
+- `sulala init [dir]` — create config/context/registry and copy `.env.example` → `.env`
+
+**Onboard & daemon (global install):** Run `sulala onboard` to create `~/.sulala` and a default `.env`; the browser opens to **http://127.0.0.1:2026/onboard** to add API keys (saved to `~/.sulala/.env`). Run `sulala onboard --install-daemon` to install a background service (launchd on macOS, systemd on Linux) so the agent runs at login. Logs: `~/.sulala/logs/`. Use `sulala stop` / `sulala start` to stop or start the daemon; `sulala onboard --uninstall-daemon` to remove it.
 
-**Onboard & daemon (global install):** After `npm i -g @sulala/agent`, run `sulala onboard` to create `~/.sulala` and a default `.env`; your browser opens to **http://127.0.0.1:3000/onboard** where you can add API keys (saved to `~/.sulala/.env`). Then `sulala onboard --install-daemon` to install a background service (launchd on macOS, systemd on Linux) so the agent runs at login; the browser opens again after the daemon starts. Logs: `~/.sulala/logs/`. **Stop/start:** `sulala stop` stops the agent daemon; `sulala start` starts it again. To remove the daemon: `sulala onboard --uninstall-daemon`.
+**Works on any device:** The published package includes the default skills registry and bundled skills (`registry/`, `context/`), so `sulala skill list` and the agent work out of the box. Optionally set `SKILLS_REGISTRY_URL` for a remote skills store.
 
-**Works on any device:** The published package includes the default skills registry and bundled skills (`registry/`, `context/`), so `sulala skill list` and the agent work out of the box without setting `SKILLS_REGISTRY_URL`. Optional: point `SKILLS_REGISTRY_URL` at a remote store for more skills.
+**Hub & integrations**
 
-Set `GATEWAY_URL` and optionally `GATEWAY_API_KEY` when using gateway commands. Set `SULALA_SKILLS_DIR` and `AGENT_CONTEXT_PATH` for skill paths.
+- **Skills hub:** [hub.sulala.ai](https://hub.sulala.ai) — upload skills for the agent and share them with others; install via `sulala skill list` / `sulala skill install` when using that registry.
+- **Integrations:** Add more integrations (Gmail, Slack, GitHub, Calendar, etc.) for the agent; use the dashboard Integrations area or the integrations catalog to connect and manage them.
+- **Portal (testing):** [portal.sulala.ai](https://portal.sulala.ai) — connect OAuth apps for testing (Gmail, Calendar, Slack, GitHub, etc.). Set `PORTAL_GATEWAY_URL` and `PORTAL_API_KEY` in the agent (e.g. in dashboard Settings → Portal) so it can list connections and get tokens. See [docs/sulalahub.md](docs/sulalahub.md) and `context/portal-integrations.md`.
 
-**Agent runner:** Multi-turn sessions with optional tool use. Create a session, then send messages to run the agent loop (model can call tools; built-in `run_task` enqueues background tasks). See [docs/ROADMAP_AGENT_RUNNER.md](docs/ROADMAP_AGENT_RUNNER.md) and [docs/AGENT_API.md](docs/AGENT_API.md).
-- `GET /api/agent/sessions` — list sessions (query: `limit`).
-- `POST /api/agent/sessions` — create or get session (body: `{ "session_key": "my-chat", "meta": {} }`).
-- `GET /api/agent/sessions/:id` — get session and message history.
+**Env for CLI/gateway:** Set `GATEWAY_URL` and optionally `GATEWAY_API_KEY` for gateway commands; `SULALA_SKILLS_DIR` and `AGENT_CONTEXT_PATH` for skill paths.
+
+**Agent runner:** Multi-turn sessions with optional tool use. See [docs/roadmap-agent-runner.md](docs/roadmap-agent-runner.md) and [docs/agent-api.md](docs/agent-api.md).
+
+- `GET /api/agent/sessions` — list sessions (query: `limit`)
+- `POST /api/agent/sessions` — create or get session (body: `{ "session_key": "my-chat", "meta": {} }`)
+- `GET /api/agent/sessions/:id` — get session and message history
 - `POST /api/agent/sessions/:id/messages` — send a message and run the agent turn (body: `{ "message": "…", "system_prompt": "…", "provider": "openai", "timeout_ms": 300000 }`). Returns `{ finalContent, messages, turnCount }`. Runs are serialized per session; client disconnect or timeout aborts the run (`AGENT_TIMEOUT_MS` in env or `timeout_ms` in body).
 
-**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`).
+**AI models:** OpenAI, OpenRouter, Claude, Gemini, Ollama (local). See [docs/models.md](docs/models.md) for model IDs and env vars.
 
-**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: `.env` (`WATCH_FOLDERS`) or `config/watched.json` (array `folders`); both are merged. Gateway auth: `GATEWAY_API_KEY`; webhooks: `WEBHOOK_URL` or `WEBHOOK_URLS` (optional `WEBHOOK_SECRET`). Default AI 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`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`. See `.env.example` and [docs/config.md](docs/config.md).
+
+**Docker:** Dashboard is served from the gateway.
 
-**Docker:** Build and run with dashboard served from the gateway:
 ```bash
 docker compose up --build
 ```
-Then open http://localhost:3000. Mount `./config` for watched folders; data is stored in a named volume.
+
+Open http://localhost:2026. Mount `./config` for watched folders; data is in a named volume.
 
 ## Requirements
 

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.