@symerian/symi 3.0.17 → 3.0.18

package/skills/connect-email/SKILL.md

@@ -1,142 +0,0 @@
----
-name: connect-email
-description: Connect a user's email account (Outlook 365 or Gmail) to Symi. Use when the user asks to connect, link, set up, configure, or troubleshoot email — including any mention of "my email", "work email", "outlook", "gmail", "microsoft 365", "m365", "google workspace", or "inbox". Precheck for an existing connection, ask Gmail or Outlook, then walk through the matching setup. Covers the `/outlook login` device-code flow and the full Gmail `hooks.gmail` Pub/Sub setup.
-triggers: [connect-email, connect, email]
----
-
-# Connect Email
-
-Symi has two email integrations. **Do not invent steps. Do not claim email is unsupported.** Follow this skill end-to-end.
-
-| Integration     | Use when                                                                                             | How to connect                                                                                        |
-| --------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| **Outlook 365** | Microsoft 365 work/school account, personal `outlook.com` / `hotmail.com` / `live.com`               | User sends `/outlook login` in chat → Microsoft device-code flow → tools become available immediately |
-| **Gmail**       | Google Workspace, personal Gmail — **and** the user wants incoming mail to auto-create Symi sessions | Google Cloud Pub/Sub + `hooks.gmail` config (multi-step setup)                                        |
-
-## Step 0 — Precheck the connection state
-
-Before asking "Gmail or Outlook?", check what's already connected so you don't ask a user who's already set up.
-
-1. **Outlook.** Your current system prompt already contains a line starting with `[Outlook 365]`, injected by the `outlook` plugin's `before_prompt_build` hook. If it reads _"Connected as <email>"_, Outlook is active — acknowledge it ("I can see you're already connected as X") and ask whether the user wants to add a second account or do something else.
-2. **Gmail.** Read `~/.symi/symi.json`. If it has a `hooks.gmail` block with at least `account` and `topic` set, Gmail is configured — again, acknowledge before offering to re-setup.
-
-If neither is connected — or the user explicitly wants a _different_ account than what's shown — continue.
-
-## Step 1 — Ask the user: Gmail or Outlook?
-
-One plain question. Do not assume. The correct branch depends on which mail provider the user actually has.
-
-## Step 2a — Outlook branch
-
-1. Ask the user to **type `/outlook login` in chat themselves**. Chat commands are intercepted by the command dispatcher only when the user sends them — if you emit `/outlook login` as assistant text it is just text, not a command.
-2. They will receive a reply with a Microsoft device-code URL (typically `https://login.microsoft.com/device`) and an 8-character code. The code expires in 15 minutes.
-3. The user opens the URL in any browser, signs in with their Microsoft account, pastes the code, and approves access.
-4. Tokens are persisted to `~/.symi/credentials/outlook.json` (mode 0600). From the next turn, the `before_prompt_build` hook will inject `[Outlook 365] Connected as <email>` into your system context automatically.
-5. Ask the user to send `/outlook status` to confirm. On success these seven tools are live for your use:
-   - `outlook_list` — list messages in a folder (`inbox`, `sentitems`, `drafts`, `archive`, `junkemail`), optional unread filter
-   - `outlook_read` — fetch the full body of a message by id (auto-marks read)
-   - `outlook_send` — new message with To/CC, subject, body
-   - `outlook_reply` — reply or reply-all to an existing message id
-   - `outlook_search` — keyword search across subject / body / sender
-   - `outlook_folders` — list folders with unread / total counts
-   - `outlook_move` — move a message to another folder
-
-### Outlook limitations to tell the user up front
-
-- **Plain-text body only.** No HTML formatting, no attachments (send or receive).
-- **Pull-only.** Symi does not receive incoming Outlook mail as Symi conversations. The user has to ask ("any new mail?") and you call `outlook_list` / `outlook_search`. There is no push, webhook, or background poll for Outlook today — if the user wants inbound-triggered sessions, they need Gmail.
-- **No Graph API retry/backoff yet.** A transient Graph 5xx surfaces as an error on the first try; re-running the tool usually succeeds.
-
-## Step 2b — Gmail branch (full walkthrough)
-
-Gmail is heavier because Google requires Pub/Sub for push notifications. End result: when new mail lands in the watched label, Google publishes to a Pub/Sub topic; a push subscription POSTs to Symi's webhook; Symi creates a `hook:gmail:<id>` session that you then reply into as the agent.
-
-### Prerequisites — verify with the user before starting
-
-- [ ] Access to a **Google Cloud project** (they can create one free at [console.cloud.google.com](https://console.cloud.google.com)).
-- [ ] `gcloud` CLI installed. On macOS: `brew install --cask google-cloud-sdk`. On Linux: follow the [gcloud install guide](https://cloud.google.com/sdk/docs/install).
-- [ ] OAuth credentials for the Gmail API, managed via `gogcli`. See `skills/gog/SKILL.md` for gogcli setup (`gog auth credentials /path/to/client_secret.json` then `gog auth add <email> --services gmail`).
-- [ ] Symi's webhook endpoint reachable by Google's push service. Either the Symi host is publicly reachable, **or** Tailscale is configured (`tailscale.mode: "serve"` for private, `"funnel"` for public-over-Tailscale).
-
-If any prerequisite is missing, stop and help the user install/configure it before continuing.
-
-### Step-by-step setup
-
-1. **Authenticate gcloud** — `gcloud auth login` and `gcloud config set project <project-id>`.
-2. **Set up gogcli OAuth** — follow the `gog` skill: `gog auth credentials /path/to/client_secret.json`, then `gog auth add <email> --services gmail`.
-3. **Create the Pub/Sub topic**
-   ```bash
-   gcloud pubsub topics create symi-gmail
-   ```
-4. **Grant Gmail permission to publish to the topic**
-   ```bash
-   gcloud pubsub topics add-iam-policy-binding symi-gmail \
-     --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
-     --role=roles/pubsub.publisher
-   ```
-5. **Create the push subscription** (pointing at Symi's webhook URL)
-   ```bash
-   gcloud pubsub subscriptions create symi-gmail-sub \
-     --topic=symi-gmail \
-     --push-endpoint=<SYMI_WEBHOOK_URL>/gmail-pubsub
-   ```
-6. **Register the Gmail watch** — call `users.watch` on the Gmail API with the topic and the label to watch (normally `INBOX`). The helpers in `src/hooks/gmail-setup-utils.ts` can do this from the gateway; ask the user whether they want you to run the setup via the gateway CLI or execute the `curl` against the Gmail API manually.
-7. **Add `hooks.gmail` to `~/.symi/symi.json`**:
-
-   ```json
-   {
-     "hooks": {
-       "gmail": {
-         "account": "user@example.com",
-         "label": "INBOX",
-         "topic": "projects/<project-id>/topics/symi-gmail",
-         "subscription": "projects/<project-id>/subscriptions/symi-gmail-sub",
-         "pushToken": "<random-shared-secret>",
-         "hookUrl": "http://127.0.0.1:8788/gmail-pubsub",
-         "includeBody": true,
-         "maxBytes": 20480,
-         "renewEveryMinutes": 720,
-         "serve": { "bind": "127.0.0.1", "port": 8788, "path": "/gmail-pubsub" },
-         "tailscale": { "mode": "off" }
-       }
-     }
-   }
-   ```
-
-   Key fields:
-   - `account` — the Gmail address being watched.
-   - `label` — Gmail label/folder to watch (default `INBOX`).
-   - `topic` / `subscription` — fully-qualified Pub/Sub resource names (`projects/<id>/topics/<name>`).
-   - `pushToken` — shared secret Symi checks on incoming push requests so spoofed pushes are rejected.
-   - `hookUrl` — URL the push subscription POSTs to; must match `serve.bind` + `serve.port` + `serve.path`, or be a Tailscale serve/funnel exposing them.
-   - `includeBody` — include the email body in the prompt. `maxBytes` truncates oversized emails.
-   - `renewEveryMinutes` — Gmail `watch` expires after ~7 days; default 720 (12h) re-registers well ahead.
-   - `tailscale.mode` — `"off"` if Symi is publicly reachable; `"serve"` for a private tailnet webhook; `"funnel"` for Tailscale-exposed public endpoint.
-   - `allowUnsafeExternalContent` — leave unset. Setting `true` disables Symi's external-content safety wrapper on email content — only use after explicit user acknowledgement.
-
-8. **Restart the gateway** so it picks up the new hook config:
-   ```bash
-   systemctl --user restart symi-gateway   # Linux
-   ```
-   On macOS with the headless tmux wrapper, kill and relaunch the tmux session running `gateway-headless.sh`. Changes under `hooks.gmail` are not hot-reloaded today.
-9. **Verify** — have the user send a test email to `account`. Expected chain: Google publishes to the topic → Pub/Sub pushes to Symi's `/gmail-pubsub` endpoint → a `hook:gmail:<id>` session is created → you reply to it in the normal Symi conversation flow. Confirm the user sees the test email arrive as a Symi session.
-
-### Gmail limitations to tell the user
-
-- Inbound only works while the watch is live. If `renewEveryMinutes` lapses, the Pub/Sub subscription fails, or the IAM binding gets removed, mail stops arriving — the gateway doctor (`symi doctor`) has checks for this.
-- Outgoing mail uses the reply path of whichever session/agent handles the inbound — it is not a native SMTP sender tool like `outlook_send`. For "compose a new email from scratch" workflows, Outlook is simpler.
-- `maxBytes` truncates very large emails so the prompt stays usable — set higher if the user routinely needs full message bodies.
-
-## Which should I recommend?
-
-- **Microsoft 365 / outlook.com / hotmail.com / live.com** → Outlook. Two-minute setup.
-- **Gmail or Google Workspace**, user wants to **send mail on demand only** → Gmail via the `gog` CLI tools (no Pub/Sub needed) is simpler than the full `hooks.gmail` flow — mention this option.
-- **Gmail or Google Workspace**, user wants **incoming mail to auto-create Symi sessions** → Full Gmail Pub/Sub setup (Step 2b).
-- User wants _both send and auto-receive in Outlook_ → not available today; push/poll for Outlook is not implemented.
-
-## References
-
-- Gmail Pub/Sub concept doc: `docs/automation/gmail-pubsub.md`
-- gog (Google Workspace CLI): `skills/gog/SKILL.md`
-- Outlook plugin source: `extensions/outlook/` (tools in `src/tools.ts`, OAuth in `src/auth.ts`)
-- Config types: `src/config/types.hooks.ts` (`HooksGmailConfig`)

package/skills/document-generation/SKILL.md

@@ -1,83 +0,0 @@
----
-name: document-generation
-description: Generate Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and PDF documents via npm packages bundled with Symi. Write a short Node.js script (.cjs for CommonJS), execute via exec with host=gateway. Use when the user asks to create, generate, or export documents.
-triggers: [document, docx, xlsx, pptx, pdf, word, excel, powerpoint, generate, export, file]
----
-
-# Document Generation
-
-Symi ships with these npm packages bundled for document generation via the `exec` tool:
-
-- **`docx`** — create `.docx` (Word) files with headings, paragraphs, tables, images, styles.
-- **`exceljs`** — create `.xlsx` (Excel) files with sheets, formulas, formatting, charts.
-- **`pptxgenjs`** — create `.pptx` (PowerPoint) files with slides, layouts, text, images, charts.
-- **`pdfkit`** — create `.pdf` files with text, images, tables, vector graphics.
-
-These are real `dependencies` in Symi's `package.json` — they install with Symi automatically. No separate setup step.
-
-## How to invoke
-
-When the user asks to **create, generate, or export** a document:
-
-1. Write a short Node.js script. Save it with the `.cjs` extension so CommonJS `require()` resolves correctly even though Symi's own package is `"type": "module"`.
-2. Execute via the `exec` tool with `host: "gateway"` — the packages are installed in Symi's own `node_modules`, which the gateway host can resolve from.
-3. Write the output to a path the user can pick up — typically the workspace dir, `~/Downloads/`, or wherever the user named.
-
-## Minimal example — Word doc
-
-```js
-// gen.cjs
-const { Document, Packer, Paragraph, TextRun, HeadingLevel } = require("docx");
-const fs = require("fs");
-
-const doc = new Document({
-  sections: [
-    {
-      children: [
-        new Paragraph({ heading: HeadingLevel.TITLE, children: [new TextRun("Report")] }),
-        new Paragraph({ children: [new TextRun("Body content here.")] }),
-      ],
-    },
-  ],
-});
-
-Packer.toBuffer(doc).then((buf) => {
-  fs.writeFileSync("/tmp/report.docx", buf);
-});
-```
-
-Then `exec({ host: "gateway", command: "node gen.cjs" })`.
-
-The script must run on the gateway host because that's where Symi's `node_modules` live — the sandbox and remote nodes do NOT have these packages.
-
-## Other formats
-
-```js
-// xlsx
-const ExcelJS = require("exceljs");
-const wb = new ExcelJS.Workbook();
-const sheet = wb.addWorksheet("Sheet1");
-sheet.getCell("A1").value = "Hello";
-await wb.xlsx.writeFile("/tmp/out.xlsx");
-
-// pptx
-const PptxGenJS = require("pptxgenjs");
-const pptx = new PptxGenJS();
-const slide = pptx.addSlide();
-slide.addText("Hello", { x: 1, y: 1, w: 4, h: 1 });
-await pptx.writeFile({ fileName: "/tmp/out.pptx" });
-
-// pdf
-const PDFDocument = require("pdfkit");
-const fs = require("fs");
-const pdf = new PDFDocument();
-pdf.pipe(fs.createWriteStream("/tmp/out.pdf"));
-pdf.text("Hello");
-pdf.end();
-```
-
-## What NOT to do
-
-- **Don't use Pandoc, LibreOffice, or other CLI converters** unless the user specifically asks. The bundled npm packages are faster, more reliable, and don't require external binaries.
-- **Don't try to generate documents from the sandbox host** — the packages live in Symi's own `node_modules` on the gateway host.
-- **Don't dump 10KB of HTML and call it a "document"**. Use the structured generators above.

package/skills/eightctl/SKILL.md

@@ -1,51 +0,0 @@
----
-name: eightctl
-description: Control Eight Sleep pods (status, temperature, alarms, schedules).
-homepage: https://eightctl.sh
-metadata:
-  {
-    "symi":
-      {
-        "emoji": "🎛️",
-        "requires": { "bins": ["eightctl"] },
-        "install":
-          [
-            {
-              "id": "go",
-              "kind": "go",
-              "module": "github.com/steipete/eightctl/cmd/eightctl@latest",
-              "bins": ["eightctl"],
-              "label": "Install eightctl (go)",
-            },
-          ],
-      },
-  }
-triggers: [eightctl]
----
-
-# eightctl
-
-Use `eightctl` for Eight Sleep pod control. Requires auth.
-
-Auth
-
-- Config: `~/.config/eightctl/config.yaml`
-- Env: `EIGHTCTL_EMAIL`, `EIGHTCTL_PASSWORD`
-
-Quick start
-
-- `eightctl status`
-- `eightctl on|off`
-- `eightctl temp 20`
-
-Common tasks
-
-- Alarms: `eightctl alarm list|create|dismiss`
-- Schedules: `eightctl schedule list|create|update`
-- Audio: `eightctl audio state|play|pause`
-- Base: `eightctl base info|angle`
-
-Notes
-
-- API is unofficial and rate-limited; avoid repeated logins.
-- Confirm before changing temperature or alarms.

package/skills/food-order/SKILL.md

@@ -1,49 +0,0 @@
----
-name: food-order
-description: Reorder Foodora orders + track ETA/status with ordercli. Never confirm without explicit user approval. Triggers: order food, reorder, track ETA.
-homepage: https://ordercli.sh
-metadata: {"symi":{"emoji":"🥡","requires":{"bins":["ordercli"]},"install":[{"id":"go","kind":"go","module":"github.com/steipete/ordercli/cmd/ordercli@latest","bins":["ordercli"],"label":"Install ordercli (go)"}]}}
-triggers: [food-order, food, order]
----
-
-# Food order (Foodora via ordercli)
-
-Goal: reorder a previous Foodora order safely (preview first; confirm only on explicit user “yes/confirm/place the order”).
-
-Hard safety rules
-
-- Never run `ordercli foodora reorder ... --confirm` unless user explicitly confirms placing the order.
-- Prefer preview-only steps first; show what will happen; ask for confirmation.
-- If user is unsure: stop at preview and ask questions.
-
-Setup (once)
-
-- Country: `ordercli foodora countries` → `ordercli foodora config set --country AT`
-- Login (password): `ordercli foodora login --email you@example.com --password-stdin`
-- Login (no password, preferred): `ordercli foodora session chrome --url https://www.foodora.at/ --profile "Default"`
-
-Find what to reorder
-
-- Recent list: `ordercli foodora history --limit 10`
-- Details: `ordercli foodora history show <orderCode>`
-- If needed (machine-readable): `ordercli foodora history show <orderCode> --json`
-
-Preview reorder (no cart changes)
-
-- `ordercli foodora reorder <orderCode>`
-
-Place reorder (cart change; explicit confirmation required)
-
-- Confirm first, then run: `ordercli foodora reorder <orderCode> --confirm`
-- Multiple addresses? Ask user for the right `--address-id` (take from their Foodora account / prior order data) and run:
-  - `ordercli foodora reorder <orderCode> --confirm --address-id <id>`
-
-Track the order
-
-- ETA/status (active list): `ordercli foodora orders`
-- Live updates: `ordercli foodora orders --watch`
-- Single order detail: `ordercli foodora order <orderCode>`
-
-Debug / safe testing
-
-- Use a throwaway config: `ordercli --config /tmp/ordercli.json ...`

package/skills/gemini/SKILL.md

@@ -1,44 +0,0 @@
----
-name: gemini
-description: Gemini CLI for one-shot Q&A, summaries, and generation.
-homepage: https://ai.google.dev/
-metadata:
-  {
-    "symi":
-      {
-        "emoji": "♊️",
-        "requires": { "bins": ["gemini"] },
-        "install":
-          [
-            {
-              "id": "brew",
-              "kind": "brew",
-              "formula": "gemini-cli",
-              "bins": ["gemini"],
-              "label": "Install Gemini CLI (brew)",
-            },
-          ],
-      },
-  }
-triggers: [gemini]
----
-
-# Gemini CLI
-
-Use Gemini in one-shot mode with a positional prompt (avoid interactive mode).
-
-Quick start
-
-- `gemini "Answer this question..."`
-- `gemini --model <name> "Prompt..."`
-- `gemini --output-format json "Return JSON"`
-
-Extensions
-
-- List: `gemini --list-extensions`
-- Manage: `gemini extensions <command>`
-
-Notes
-
-- If auth is required, run `gemini` once interactively and follow the login flow.
-- Avoid `--yolo` for safety.