@spinabot/brigade 0.1.2 → 1.0.1

package/skills/imsg/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: imsg
+description: iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.
+homepage: https://imsg.to
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📨",
+        "os": ["darwin"],
+        "requires": { "bins": ["imsg"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/imsg",
+              "bins": ["imsg"],
+              "label": "Install imsg (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# imsg
+
+Use `imsg` to read and send iMessage/SMS via macOS Messages.app.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- User explicitly asks to send iMessage or SMS
+- Reading iMessage conversation history
+- Checking recent Messages.app chats
+- Sending to phone numbers or Apple IDs
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Telegram messages → use `message` tool with `channel:telegram`
+- Signal messages → use Signal channel if configured
+- WhatsApp messages → use WhatsApp channel if configured
+- Discord messages → use `message` tool with `channel:discord`
+- Slack messages → use `slack` skill
+- Group chat management (adding/removing members) → not supported
+- Bulk/mass messaging → always confirm with user first
+- Replying in current conversation → just reply normally (Brigade routes automatically)
+
+## Requirements
+
+- macOS with Messages.app signed in
+- Full Disk Access for terminal
+- Automation permission for Messages.app (for sending)
+
+## Common Commands
+
+### List Chats
+
+```bash
+imsg chats --limit 10 --json
+```
+
+### View History
+
+```bash
+# By chat ID
+imsg history --chat-id 1 --limit 20 --json
+
+# With attachments info
+imsg history --chat-id 1 --limit 20 --attachments --json
+```
+
+### Watch for New Messages
+
+```bash
+imsg watch --chat-id 1 --attachments
+```
+
+### Send Messages
+
+```bash
+# Text only
+imsg send --to "+14155551212" --text "Hello!"
+
+# With attachment
+imsg send --to "+14155551212" --text "Check this out" --file /path/to/image.jpg
+
+# Specify service
+imsg send --to "+14155551212" --text "Hi" --service imessage
+imsg send --to "+14155551212" --text "Hi" --service sms
+```
+
+## Service Options
+
+- `--service imessage` — Force iMessage (requires recipient has iMessage)
+- `--service sms` — Force SMS (green bubble)
+- `--service auto` — Let Messages.app decide (default)
+
+## Safety Rules
+
+1. **Always confirm recipient and message content** before sending
+2. **Never send to unknown numbers** without explicit user approval
+3. **Be careful with attachments** — confirm file path exists
+4. **Rate limit yourself** — don't spam
+
+## Example Workflow
+
+User: "Text mom that I'll be late"
+
+```bash
+# 1. Find mom's chat
+imsg chats --limit 20 --json | jq '.[] | select(.displayName | contains("Mom"))'
+
+# 2. Confirm with user
+# "Found Mom at +1555123456. Send 'I'll be late' via iMessage?"
+
+# 3. Send after confirmation
+imsg send --to "+1555123456" --text "I'll be late"
+```

package/skills/lead-scout/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: lead-scout
+description: How to find and VERIFY business leads (any niche, any city) — especially "businesses without a website" prospecting. Decides "no website" by SEARCHING the business name, not by a map button. Use whenever the user asks to find businesses, shops, vendors, professionals, or sales leads in a location. No API key needed — web_search + the browser do everything.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🎯",
+      },
+  }
+---
+
+# Lead Scout
+
+Goal: a **verified lead = a business that has NO website of its own**, confirmed by *searching for it* — the use case is selling websites to businesses that don't have one. Keyless: `web_search` + the browser do all the work, no API key.
+
+## The rule — what counts as "having a website"
+A business has a website only if it has its **own site**: an official domain (e.g. `cafeborkar.com`, `artjuna.in`). These do **NOT** count as a website:
+- **Social pages** — instagram.com, facebook.com
+- **Aggregators / directories** — zomato, swiggy, justdial, tripadvisor, magicpin, dineout
+- Its **Google Maps / Google Business** listing
+
+So if searching for the business surfaces **only** those, it has **no website → it's a lead**.
+
+## Method — decide by SEARCH, never by a map button
+1. **Get candidate names — `web_search` FIRST** (don't drive Maps unless search is unavailable):
+   - `web_search "<niche> in <city>"` returns businesses + their domains. Often this single search already answers it — a business appearing only on aggregators/social with no own domain is your lead.
+   - ONLY if `web_search` is down/rate-limited: browser `navigate` to `https://www.google.com/maps/search/<niche>+in+<city>`, then **one** `snapshot` (snapshotFormat:`"text"`)/`evaluate` to read the whole list at once (never screenshot or click each listing). `scroll` (to:`"bottom"`) + snapshot again for more.
+2. **Decide per business with a search** — THIS is the step that determines "no website":
+   - `web_search "<business name> <city>"`. (If `web_search` is rate-limited, run the same query in the browser: navigate to a Bing / DuckDuckGo-html / Google results URL, then `snapshot`.)
+   - Scan the results: is any result the business's **own domain** (per the rule above)?
+     - **Yes** → it HAS a website — skip it, not a lead.
+     - **Only** social / aggregator / Maps results → **no website → it's a lead.**
+   - Not sure which result is theirs? Open the top non-social hit and `snapshot` to confirm whose site it is.
+3. **Report** each lead with the **evidence**: name, area/address + phone if found, and *why* it's a lead — e.g. *"searched 'Cafe Borkar Panaji' — only an Instagram page and a Zomato listing came up, no own website."*
+
+## Phone / address
+Read them from the search results or the business's own social page. Google Maps hides the phone behind a sign-in in its UI — don't fight that panel; the number is usually right there in the search results or on their Instagram/Facebook.
+
+## Anti-patterns
+- **NEVER decide "no website" from a missing Google Maps "Website" button.** That only means nobody linked a site to Google — the business may well have one. The ONLY valid way to decide is to **search the business name** and see whether its own site appears.
+- Don't screenshot a listing and read it visually, and don't click into each listing one-by-one — read a list with ONE `snapshot`/`evaluate`, then decide by search.
+- Don't spawn a sub-agent just to look up or verify a list — do it inline; a lookup doesn't need a crew.
+- Don't report a lead you haven't actually searched for; never invent phone numbers from memory.
+- If you find yourself repeating the same action without new results, STOP and report what you have so far.
+- Don't treat an aggregator/directory page as the business's website or as the source of truth.

package/skills/mcporter/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: mcporter
+description: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.
+homepage: http://mcporter.dev
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📦",
+        "requires": { "bins": ["mcporter"] },
+        "install":
+          [
+            {
+              "id": "node",
+              "kind": "node",
+              "package": "mcporter",
+              "bins": ["mcporter"],
+              "label": "Install mcporter (node)",
+            },
+          ],
+      },
+  }
+---
+
+# mcporter
+
+Use `mcporter` to work with MCP servers directly.
+
+Quick start
+
+- `mcporter list`
+- `mcporter list <server> --schema`
+- `mcporter call <server.tool> key=value`
+
+Call tools
+
+- Selector: `mcporter call linear.list_issues team=ENG limit:5`
+- Function syntax: `mcporter call "linear.create_issue(title: \"Bug\")"`
+- Full URL: `mcporter call https://api.example.com/mcp.fetch url:https://example.com`
+- Stdio: `mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com`
+- JSON payload: `mcporter call <server.tool> --args '{"limit":5}'`
+
+Auth + config
+
+- OAuth: `mcporter auth <server | url> [--reset]`
+- Config: `mcporter config list|get|add|remove|import|login|logout`
+
+Daemon
+
+- `mcporter daemon start|status|stop|restart`
+
+Codegen
+
+- CLI: `mcporter generate-cli --server <name>` or `--command <url>`
+- Inspect: `mcporter inspect-cli <path> [--json]`
+- TS: `mcporter emit-ts <server> --mode client|types`
+
+Notes
+
+- Config default: `./config/mcporter.json` (override with `--config`).
+- Prefer `--output json` for machine-readable results.

package/skills/model-usage/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: model-usage
+description: Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📊",
+        "os": ["darwin"],
+        "requires": { "bins": ["codexbar"] },
+        "install":
+          [
+            {
+              "id": "brew-cask",
+              "kind": "brew",
+              "formula": "steipete/tap/codexbar",
+              "bins": ["codexbar"],
+              "label": "Install CodexBar (brew cask)",
+            },
+          ],
+      },
+  }
+---
+
+# Model usage
+
+## Overview
+
+Get per-model usage cost from CodexBar's local cost logs. Supports "current model" (most recent daily entry) or "all models" summaries for Codex or Claude.
+
+TODO: add Linux CLI support guidance once CodexBar CLI install path is documented for Linux.
+
+## Quick start
+
+1. Fetch cost JSON via CodexBar CLI or pass a JSON file.
+2. Use the bundled script to summarize by model.
+
+```bash
+python {baseDir}/scripts/model_usage.py --provider codex --mode current
+python {baseDir}/scripts/model_usage.py --provider codex --mode all
+python {baseDir}/scripts/model_usage.py --provider claude --mode all --format json --pretty
+```
+
+## Current model logic
+
+- Uses the most recent daily row with `modelBreakdowns`.
+- Picks the model with the highest cost in that row.
+- Falls back to the last entry in `modelsUsed` when breakdowns are missing.
+- Override with `--model <name>` when you need a specific model.
+
+## Inputs
+
+- Default: runs `codexbar cost --format json --provider <codex|claude>`.
+- File or stdin:
+
+```bash
+codexbar cost --provider codex --format json > /tmp/cost.json
+python {baseDir}/scripts/model_usage.py --input /tmp/cost.json --mode all
+cat /tmp/cost.json | python {baseDir}/scripts/model_usage.py --input - --mode current
+```
+
+## Output
+
+- Text (default) or JSON (`--format json --pretty`).
+- Values are cost-only per model; tokens are not split by model in CodexBar output.
+
+## References
+
+- Read `references/codexbar-cli.md` for CLI flags and cost JSON fields.

package/skills/nano-pdf/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: nano-pdf
+description: Edit PDFs with natural-language instructions using the nano-pdf CLI.
+homepage: https://pypi.org/project/nano-pdf/
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📄",
+        "requires": { "bins": ["nano-pdf"] },
+        "install":
+          [
+            {
+              "id": "uv",
+              "kind": "uv",
+              "package": "nano-pdf",
+              "bins": ["nano-pdf"],
+              "label": "Install nano-pdf (uv)",
+            },
+          ],
+      },
+  }
+---
+
+# nano-pdf
+
+Use `nano-pdf` to apply edits to a specific page in a PDF using a natural-language instruction.
+
+## Quick start
+
+```bash
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+```
+
+Notes:
+
+- Page numbers are 0-based or 1-based depending on the tool’s version/config; if the result looks off by one, retry with the other.
+- Always sanity-check the output PDF before sending it out.

package/skills/node-connect/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: node-connect
+description: Diagnose Brigade node connection and pairing failures for Android, iOS, and macOS companion apps. Use when QR/setup code/manual connect fails, local Wi-Fi works but VPS/tailnet does not, or errors mention pairing required, unauthorized, bootstrap token invalid or expired, gateway.bind, gateway.remote.url, Tailscale, or plugins.entries.device-pair.config.publicUrl.
+---
+
+# Node Connect
+
+Goal: find the one real route from node -> gateway, verify Brigade is advertising that route, then fix pairing/auth.
+
+## Topology first
+
+Decide which case you are in before proposing fixes:
+
+- same machine / emulator / USB tunnel
+- same LAN / local Wi-Fi
+- same Tailscale tailnet
+- public URL / reverse proxy
+
+Do not mix them.
+
+- Local Wi-Fi problem: do not switch to Tailscale unless remote access is actually needed.
+- VPS / remote gateway problem: do not keep debugging `localhost` or LAN IPs.
+
+## If ambiguous, ask first
+
+If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
+
+Ask for:
+
+- which route they intend: same machine, same LAN, Tailscale tailnet, or public URL
+- whether they used QR/setup code or manual host/port
+- the exact app text/status/error, quoted exactly if possible
+- whether `brigade devices list` shows a pending pairing request
+
+Do not guess from `can't connect`.
+
+## Canonical checks
+
+Prefer `brigade qr --json`. It uses the same setup-code payload Android scans.
+
+```bash
+brigade config get gateway.mode
+brigade config get gateway.bind
+brigade config get gateway.tailscale.mode
+brigade config get gateway.remote.url
+brigade config get gateway.auth.mode
+brigade config get gateway.auth.allowTailscale
+brigade config get plugins.entries.device-pair.config.publicUrl
+brigade qr --json
+brigade devices list
+brigade nodes status
+```
+
+If this Brigade instance is pointed at a remote gateway, also run:
+
+```bash
+brigade qr --remote --json
+```
+
+If Tailscale is part of the story:
+
+```bash
+tailscale status --json
+```
+
+## Read the result, not guesses
+
+`brigade qr --json` success means:
+
+- `gatewayUrl`: this is the actual endpoint the app should use.
+- `urlSource`: this tells you which config path won.
+
+Common good sources:
+
+- `gateway.bind=lan`: same Wi-Fi / LAN only
+- `gateway.bind=tailnet`: direct tailnet access
+- `gateway.tailscale.mode=serve` or `gateway.tailscale.mode=funnel`: Tailscale route
+- `plugins.entries.device-pair.config.publicUrl`: explicit public/reverse-proxy route
+- `gateway.remote.url`: remote gateway route
+
+## Root-cause map
+
+If `brigade qr --json` says `Gateway is only bound to loopback`:
+
+- remote node cannot connect yet
+- fix the route, then generate a fresh setup code
+- `gateway.bind=auto` is not enough if the effective QR route is still loopback
+- same LAN: use `gateway.bind=lan`
+- same tailnet: prefer `gateway.tailscale.mode=serve` or use `gateway.bind=tailnet`
+- public internet: set a real `plugins.entries.device-pair.config.publicUrl` or `gateway.remote.url`
+
+If `gateway.bind=tailnet set, but no tailnet IP was found`:
+
+- gateway host is not actually on Tailscale
+
+If `qr --remote requires gateway.remote.url`:
+
+- remote-mode config is incomplete
+
+If the app says `pairing required`:
+
+- network route and auth worked
+- approve the pending device
+
+```bash
+brigade devices list
+brigade devices approve --latest
+```
+
+If the app says `bootstrap token invalid or expired`:
+
+- old setup code
+- generate a fresh one and rescan
+- do this after any URL/auth fix too
+
+If the app says `unauthorized`:
+
+- wrong token/password, or wrong Tailscale expectation
+- for Tailscale Serve, `gateway.auth.allowTailscale` must match the intended flow
+- otherwise use explicit token/password
+
+## Fast heuristics
+
+- Same Wi-Fi setup + gateway advertises `127.0.0.1`, `localhost`, or loopback-only config: wrong.
+- Remote setup + setup/manual uses private LAN IP: wrong.
+- Tailnet setup + gateway advertises LAN IP instead of MagicDNS / tailnet route: wrong.
+- Public URL set but QR still advertises something else: inspect `urlSource`; config is not what you think.
+- `brigade devices list` shows pending requests: stop changing network config and approve first.
+
+## Fix style
+
+Reply with one concrete diagnosis and one route.
+
+If there is not enough signal yet, ask for setup + exact app text instead of guessing.
+
+Good:
+
+- `The gateway is still loopback-only, so a node on another network can never reach it. Enable Tailscale Serve, restart the gateway, run brigade qr again, rescan, then approve the pending device pairing.`
+
+Bad:
+
+- `Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.`

package/skills/notion/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: notion
+description: Notion API for creating and managing pages, databases, and blocks.
+homepage: https://developers.notion.com
+metadata:
+  {
+    "brigade":
+      { "emoji": "📝", "requires": { "env": ["NOTION_API_KEY"] }, "primaryEnv": "NOTION_API_KEY" },
+  }
+---
+
+# notion
+
+Use the Notion API to create/read/update pages, data sources (databases), and blocks.
+
+## Setup
+
+1. Create an integration at https://notion.so/my-integrations
+2. Copy the API key (starts with `ntn_` or `secret_`)
+3. Store it:
+
+```bash
+mkdir -p ~/.config/notion
+echo "ntn_your_key_here" > ~/.config/notion/api_key
+```
+
+4. Share target pages/databases with your integration (click "..." → "Connect to" → your integration name)
+
+## API Basics
+
+All requests need:
+
+```bash
+NOTION_KEY=$(cat ~/.config/notion/api_key)
+curl -X GET "https://api.notion.com/v1/..." \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json"
+```
+
+> **Note:** The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called "data sources" in the API.
+
+## Common Operations
+
+**Search for pages and data sources:**
+
+```bash
+curl -X POST "https://api.notion.com/v1/search" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "page title"}'
+```
+
+**Get page:**
+
+```bash
+curl "https://api.notion.com/v1/pages/{page_id}" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03"
+```
+
+**Get page content (blocks):**
+
+```bash
+curl "https://api.notion.com/v1/blocks/{page_id}/children" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03"
+```
+
+**Create page in a data source:**
+
+```bash
+curl -X POST "https://api.notion.com/v1/pages" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"database_id": "xxx"},
+    "properties": {
+      "Name": {"title": [{"text": {"content": "New Item"}}]},
+      "Status": {"select": {"name": "Todo"}}
+    }
+  }'
+```
+
+**Query a data source (database):**
+
+```bash
+curl -X POST "https://api.notion.com/v1/data_sources/{data_source_id}/query" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filter": {"property": "Status", "select": {"equals": "Active"}},
+    "sorts": [{"property": "Date", "direction": "descending"}]
+  }'
+```
+
+**Create a data source (database):**
+
+```bash
+curl -X POST "https://api.notion.com/v1/data_sources" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parent": {"page_id": "xxx"},
+    "title": [{"text": {"content": "My Database"}}],
+    "properties": {
+      "Name": {"title": {}},
+      "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}},
+      "Date": {"date": {}}
+    }
+  }'
+```
+
+**Update page properties:**
+
+```bash
+curl -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{"properties": {"Status": {"select": {"name": "Done"}}}}'
+```
+
+**Add blocks to page:**
+
+```bash
+curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
+  -H "Authorization: Bearer $NOTION_KEY" \
+  -H "Notion-Version: 2025-09-03" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "children": [
+      {"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "Hello"}}]}}
+    ]
+  }'
+```
+
+## Property Types
+
+Common property formats for database items:
+
+- **Title:** `{"title": [{"text": {"content": "..."}}]}`
+- **Rich text:** `{"rich_text": [{"text": {"content": "..."}}]}`
+- **Select:** `{"select": {"name": "Option"}}`
+- **Multi-select:** `{"multi_select": [{"name": "A"}, {"name": "B"}]}`
+- **Date:** `{"date": {"start": "2024-01-15", "end": "2024-01-16"}}`
+- **Checkbox:** `{"checkbox": true}`
+- **Number:** `{"number": 42}`
+- **URL:** `{"url": "https://..."}`
+- **Email:** `{"email": "a@b.com"}`
+- **Relation:** `{"relation": [{"id": "page_id"}]}`
+
+## Key Differences in 2025-09-03
+
+- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval
+- **Two IDs:** Each database now has both a `database_id` and a `data_source_id`
+  - Use `database_id` when creating pages (`parent: {"database_id": "..."}`)
+  - Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)
+- **Search results:** Databases return as `"object": "data_source"` with their `data_source_id`
+- **Parent in responses:** Pages show `parent.data_source_id` alongside `parent.database_id`
+- **Finding the data_source_id:** Search for the database, or call `GET /v1/data_sources/{data_source_id}`
+
+## Notes
+
+- Page/database IDs are UUIDs (with or without dashes)
+- The API cannot set database view filters — that's UI-only
+- Rate limit: ~3 requests/second average, with `429 rate_limited` responses using `Retry-After`
+- Append block children: up to 100 children per request, up to two levels of nesting in a single append request
+- Payload size limits: up to 1000 block elements and 500KB overall
+- Use `is_inline: true` when creating data sources to embed them in pages