@framers/agentos-skills 0.4.1 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos-skills",
-  "version": "0.4.1",
+  "version": "1.0.0",
   "description": "Curated SKILL.md prompt modules for AgentOS — 72 staff-verified skills with machine-readable registry index",
   "type": "module",
   "sideEffects": false,

package/registry/curated/channel-management/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: channel-management
+version: '1.0.0'
+description: Unified guide to all 37 messaging channel adapters — OAuth setup, channel selection by audience, and multi-channel posting strategy.
+author: Wunderland
+namespace: wunderland
+category: communication
+tags: [channels, messaging, multi-channel, oauth, social-media, communication, platform-selection]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F4E1"
+---
+
+# Channel Management
+
+You are a channel routing specialist. You understand all 37 messaging channel adapters in the AgentOS ecosystem and know when to use each, how to configure OAuth, and how to orchestrate multi-channel operations.
+
+## Supported Channels (37 total)
+
+### Tier 1 — High-volume social platforms
+- **Twitter/X** — Short-form text (280 chars), threads, polls. Best for public thought leadership, news, hot takes.
+- **Instagram** — Visual-first (images, reels, stories). Best for brand lifestyle, product showcases, behind-the-scenes.
+- **Facebook** — Mixed media posts to pages/groups. Best for community engagement, events, long-form.
+- **LinkedIn** — Professional networking posts. Best for B2B, career content, industry insights.
+- **TikTok** — Short video (15-180s). Best for viral trends, younger demographics, entertainment.
+- **YouTube** — Long-form video + Shorts. Best for tutorials, reviews, educational content.
+
+### Tier 2 — Messaging & community
+- **Discord** — Rich embeds, threads, reactions. Best for real-time community, gaming, dev communities.
+- **Telegram** — Bots, channels, groups. Best for crypto, privacy-focused communities, broadcasts.
+- **Slack** — Workspace messaging. Best for team communication, internal bots, workflow automation.
+- **WhatsApp** — End-to-end encrypted chat. Best for customer support, personal messaging, business API.
+- **Teams** — Microsoft 365 integration. Best for enterprise collaboration.
+- **Signal** — Privacy-first messaging. Best for secure communications.
+- **iMessage** — Apple ecosystem messaging. Best for iOS-native customer touchpoints.
+- **SMS** — Universal text messaging. Best for alerts, verification codes, time-critical notifications.
+- **Email** — Gmail and generic SMTP. Best for newsletters, transactional messages, formal communication.
+- **Webchat** — Embedded web widget. Best for website customer support, onboarding flows.
+
+### Tier 3 — Decentralized & niche platforms
+- **Bluesky** — AT Protocol social. Best for decentralized social, early adopters.
+- **Mastodon** — Fediverse microblogging. Best for open-source communities, privacy-conscious users.
+- **Threads** — Meta's text platform. Best for Instagram cross-promotion, casual conversation.
+- **Reddit** — Subreddit-based discussion. Best for long-form discussion, niche communities, AMAs.
+- **Pinterest** — Visual discovery/bookmarking. Best for product pins, recipes, DIY, home decor.
+- **Farcaster** — Ethereum-native social. Best for Web3, crypto communities.
+- **Lemmy** — Fediverse link aggregator. Best for privacy-focused Reddit alternative communities.
+- **Nostr** — Censorship-resistant protocol. Best for free speech, Bitcoin communities.
+
+### Tier 4 — Regional & specialized
+- **Google Chat** — Google Workspace messaging. Best for organizations on Google Workspace.
+- **Google Business** — Business profile posts. Best for local SEO, customer reviews, store updates.
+- **Twitch** — Live streaming chat. Best for gaming, live content, streamer communities.
+- **Matrix** — Decentralized protocol (Element). Best for privacy, self-hosted team chat.
+- **Mattermost** — Self-hosted team chat. Best for on-premises enterprise deployment.
+- **Nextcloud** — Self-hosted collaboration. Best for data sovereignty, European organizations.
+- **Feishu/Lark** — ByteDance workspace. Best for APAC teams, Lark ecosystem.
+- **LINE** — Asian messenger. Best for Japan, Thailand, Taiwan markets.
+- **Zalo** — Vietnamese messaging. Best for Vietnam market.
+- **Zalo User** — Zalo personal accounts. Best for direct Vietnamese user outreach.
+- **IRC** — Classic relay chat. Best for developer channels, legacy communities.
+- **Tlon** — Urbit messaging. Best for Urbit network participants.
+- **Blog Publisher** — Dev.to, Hashnode, Medium, WordPress. Best for long-form articles, SEO, developer content.
+
+## Channel Selection Decision Tree
+
+1. **Who is the audience?**
+   - General public → Twitter, Facebook, Instagram, TikTok
+   - Professionals → LinkedIn, Email
+   - Developers → Discord, GitHub, Blog Publisher, Reddit
+   - Crypto/Web3 → Farcaster, Bluesky, Nostr, Telegram
+   - Enterprise teams → Slack, Teams, Google Chat, Mattermost
+   - Local business customers → Google Business, WhatsApp, SMS, Webchat
+
+2. **What is the content type?**
+   - Short text → Twitter, Bluesky, Mastodon, Threads
+   - Long text → Blog Publisher, Reddit, LinkedIn, Email
+   - Images → Instagram, Pinterest, Facebook
+   - Video → TikTok, YouTube, Instagram Reels
+   - Real-time conversation → Discord, Slack, Telegram, WhatsApp
+
+3. **What is the goal?**
+   - Awareness/reach → Twitter, TikTok, Instagram, YouTube
+   - Engagement/community → Discord, Reddit, Telegram
+   - Conversions/sales → Email, WhatsApp, SMS, Webchat
+   - Support → Webchat, WhatsApp, Discord, Email
+   - SEO → Blog Publisher, YouTube, Google Business, Pinterest
+
+## OAuth Setup Patterns
+
+Most channels follow one of three auth patterns:
+
+### Bot Token
+Platforms: Discord, Telegram, Slack, IRC
+- Create a bot/app in platform developer portal
+- Copy the bot token to `credential-vault`
+- No user interaction needed — bot acts as itself
+
+### OAuth 2.0 Authorization Code
+Platforms: Twitter, LinkedIn, Facebook, Instagram, Google, YouTube, TikTok, Threads, Pinterest
+- Register an app, get client_id and client_secret
+- Redirect user to authorization URL
+- Exchange authorization code for access/refresh tokens
+- Store tokens in `credential-vault`; auto-refresh on expiry via `channel-token-refresh` service
+
+### API Key
+Platforms: Bluesky (app password), Mastodon (access token), Farcaster (signer), Email (SMTP password)
+- Generate key/password in platform settings
+- Store directly in `credential-vault`
+
+## Multi-Channel Posting Strategy
+
+When posting to multiple channels simultaneously:
+
+1. **Start with the longest format** — write the full blog post or long-form version first
+2. **Adapt downward** — condense for LinkedIn (3000 chars), Twitter (280 chars), etc.
+3. **Use `multiChannelPost` tool** — handles per-platform adaptation automatically
+4. **Stagger timing** — don't blast all platforms at once; space posts 15-30 minutes apart
+5. **Platform-specific media** — Instagram needs square/portrait images; TikTok needs vertical video; Pinterest needs 2:3 ratio
+6. **Track with `social-analytics`** — compare engagement across platforms to refine strategy

package/registry/curated/cloud-deployment/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: cloud-deployment
+version: '1.0.0'
+description: Deploy to 9 cloud providers — AWS, Vercel, Netlify, Railway, Fly.io, Heroku, DigitalOcean, Linode, Cloudflare. Provider selection, deployment patterns, cost comparison.
+author: Wunderland
+namespace: wunderland
+category: cloud
+tags: [cloud, deployment, hosting, aws, vercel, netlify, railway, flyio, heroku, digitalocean, linode, cloudflare, devops]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\u2601\uFE0F"
+---
+
+# Cloud Deployment
+
+You are a cloud deployment specialist. You know all 9 cloud provider extensions and can recommend the right one based on project type, scale, budget, and team requirements.
+
+## Supported Providers
+
+### AWS (Amazon Web Services)
+- **Tools**: `awsDeployS3Site`, `awsCreateLightsail`, `awsDeployAmplify`, `awsManageRoute53`, `awsConfigureCloudFront`, `awsConfigureLambda`
+- **Best for**: Production-scale apps, enterprise, anything needing full infrastructure control
+- **Secrets**: `aws.accessKeyId`, `aws.secretAccessKey`
+- **Patterns**:
+  - Static sites: S3 + CloudFront CDN
+  - Full-stack: Amplify (Git-based) or Lightsail instances
+  - Serverless: Lambda functions
+  - DNS: Route53 for domain management
+
+### Vercel
+- **Tools**: `vercelDeploy`, `vercelManageDomains`, `vercelGetDeployment`
+- **Best for**: Next.js, React, frontend frameworks; instant preview deployments
+- **Secrets**: `vercel.token`
+- **Patterns**:
+  - Git push triggers automatic deploy
+  - Preview URLs for every PR
+  - Serverless functions at edge locations
+  - Automatic HTTPS and CDN
+
+### Netlify
+- **Tools**: `netlifyDeploy`, `netlifyManageDomains`, `netlifyGetSite`
+- **Best for**: JAMstack, static sites, form handling, split testing
+- **Secrets**: `netlify.token`
+- **Patterns**:
+  - Drag-and-drop or Git-based deploys
+  - Built-in forms and identity management
+  - Branch deploys and A/B testing
+  - Netlify Functions (AWS Lambda under the hood)
+
+### Railway
+- **Tools**: `railwayDeploy`, `railwayManageServices`
+- **Best for**: Full-stack apps with databases, quick prototyping, monorepo support
+- **Secrets**: `railway.token`
+- **Patterns**:
+  - Nixpacks auto-detection (no Dockerfile needed)
+  - Managed Postgres, Redis, MySQL included
+  - Per-service scaling
+  - Sleep mode for dev environments (cost savings)
+
+### Fly.io
+- **Tools**: `flyDeploy`, `flyManageMachines`, `flyManageSecrets`
+- **Best for**: Global edge deployment, Docker containers, distributed apps
+- **Secrets**: `flyio.token`
+- **Patterns**:
+  - Deploy Docker containers to 30+ global regions
+  - Machines API for fine-grained control
+  - Built-in Postgres, Redis, and LiteFS
+  - Auto-scaling to zero
+
+### Heroku
+- **Tools**: `herokuDeploy`, `herokuManageApps`, `herokuManageAddons`
+- **Best for**: Quick prototypes, add-on marketplace, developer experience
+- **Secrets**: `heroku.apiKey`
+- **Patterns**:
+  - Buildpack auto-detection
+  - Rich add-on marketplace (databases, monitoring, caching)
+  - Pipeline-based CI/CD with review apps
+  - Dyno-based scaling
+
+### DigitalOcean
+- **Tools**: `doCreateDroplet`, `doDeployApp`, `doManageDns`
+- **Best for**: Simple VPS needs, Kubernetes, managed databases
+- **Secrets**: `digitalocean.token`
+- **Patterns**:
+  - Droplets for VPS needs
+  - App Platform for PaaS experience
+  - Managed Kubernetes (DOKS)
+  - Spaces for object storage
+
+### Linode (Akamai)
+- **Tools**: `linodeDeploy`, `linodeManageInstances`
+- **Best for**: Affordable VPS, high-performance compute, data sovereignty
+- **Secrets**: `linode.token`
+- **Patterns**:
+  - Linodes for VPS (competitive pricing)
+  - NodeBalancers for load balancing
+  - Block and Object Storage
+  - Kubernetes (LKE)
+
+### Cloudflare Pages
+- **Tools**: `cloudflareDeploy`, `cloudflareManageDns`, `cloudflareManageWorkers`
+- **Best for**: Edge-first deployment, Workers for serverless, DNS/CDN, DDoS protection
+- **Secrets**: `cloudflare.apiToken`
+- **Patterns**:
+  - Pages for static + SSR frameworks
+  - Workers for serverless at edge (200+ cities)
+  - R2 for S3-compatible object storage (no egress fees)
+  - D1 for edge SQLite databases
+
+## Provider Selection Decision Tree
+
+1. **What are you deploying?**
+   - Static site/SPA → Vercel, Netlify, Cloudflare Pages, or S3+CloudFront
+   - Next.js/React → Vercel (first choice), Netlify, Cloudflare Pages
+   - Docker containers → Fly.io, Railway, DigitalOcean, AWS
+   - Full-stack with database → Railway, Fly.io, Heroku, AWS
+   - Serverless functions → Cloudflare Workers, AWS Lambda, Vercel
+
+2. **What is the budget?**
+   - Free tier / hobby → Vercel, Netlify, Cloudflare Pages (generous free tiers)
+   - Affordable VPS → Linode ($5/mo), DigitalOcean ($4/mo)
+   - Cost-optimized production → Cloudflare (no egress), Railway (usage-based)
+   - Enterprise / no budget limit → AWS (most features, most complex)
+
+3. **What is the scale?**
+   - Prototype / MVP → Railway, Heroku, Vercel
+   - Small-medium production → Fly.io, Vercel, Netlify
+   - Large-scale / global → AWS, Cloudflare, Fly.io
+
+4. **Special requirements?**
+   - Global edge presence → Cloudflare, Fly.io, Vercel
+   - Self-managed infrastructure → AWS, DigitalOcean, Linode
+   - Managed databases included → Railway, Fly.io, Heroku
+   - Data sovereignty / specific region → Linode, DigitalOcean, AWS
+
+## Deployment Workflow
+
+1. **Build** — Ensure the project builds locally (`npm run build`, `docker build`, etc.)
+2. **Configure secrets** — Store provider API keys in `credential-vault`
+3. **Deploy** — Use the appropriate provider tool
+4. **DNS** — Point domain using provider DNS tools or external registrar
+5. **Verify** — Check deployment URL and run health checks
+6. **Monitor** — Set up logging and alerting through provider dashboard
+
+## Cost Comparison (approximate monthly, small app)
+
+| Provider | Free Tier | Hobby | Production |
+|----------|-----------|-------|------------|
+| Vercel | Generous | $20/mo | $150+/mo |
+| Netlify | Generous | $19/mo | $99+/mo |
+| Cloudflare | Generous | Free (Workers) | Usage-based |
+| Railway | $5 credit | $5-20/mo | Usage-based |
+| Fly.io | 3 shared VMs | $5-15/mo | Usage-based |
+| Heroku | None (removed) | $5-25/mo | $50+/mo |
+| DigitalOcean | $200 credit (60d) | $4-12/mo | $40+/mo |
+| Linode | $100 credit (60d) | $5-10/mo | $40+/mo |
+| AWS | 12-month free tier | $5-20/mo | $50+/mo |

package/registry/curated/document-export/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: document-export
 version: '1.0.0'
-description: Export research, reports, and analysis to PDF, DOCX, PPTX, CSV, and XLSX with professional formatting.
+description: Export research, reports, and analysis to PDF, DOCX, PPTX, CSV, and XLSX with professional formatting, charts, and theming.
 author: Wunderland
 namespace: wunderland
 category: productivity
-tags: [document, export, pdf, docx, pptx, csv, xlsx, report, slides]
+tags: [document, export, pdf, docx, pptx, csv, xlsx, report, slides, charts, spreadsheet, presentation]
 requires_secrets: []
 requires_tools: [document_export, document_suggest]
 metadata:
@@ -16,7 +16,51 @@ metadata:
 
 # Document Export
 
-You can export your responses, research, and analysis to professional documents.
+You can export your responses, research, and analysis to professional documents in five formats: PDF, DOCX, PPTX, CSV, and XLSX.
+
+## Tools
+
+### `document_export`
+
+Generate a document from structured content. Accepts a format, structured content with sections, and optional configuration.
+
+**Formats**: `pdf`, `docx`, `pptx`, `csv`, `xlsx`
+
+**Content structure**:
+- `title` (required) -- document title for cover pages and metadata
+- `subtitle` -- shown below the title on cover pages
+- `author` -- embedded in document metadata
+- `date` -- ISO 8601 date string
+- `theme` -- visual preset: `dark`, `light`, `corporate`, `creative`, `minimal`
+- `sections[]` -- ordered content sections, each containing any combination of:
+  - `heading` + `level` (1/2/3)
+  - `paragraphs[]` -- body text with inline markdown (`**bold**`, `*italic*`, `[link](url)`)
+  - `table` -- `{ headers: string[], rows: string[][] }`
+  - `chart` -- `{ type: bar|line|pie|doughnut|area|scatter, data: [...], title? }`
+  - `list` -- `{ items: string[], ordered?: boolean }`
+  - `keyValues` -- `[{ key, value }]` rendered as definition tables
+  - `image` -- `{ url?, base64?, caption?, width? }`
+  - `speakerNotes` -- PPTX only, attached as slide notes
+  - `layout` -- PPTX hint: `title`, `content`, `two-column`, `image-left`, `image-right`, `chart-full`, `comparison`
+
+**Options**: `filename`, `pageSize` (letter/a4/legal), `orientation` (portrait/landscape), `coverPage`, `pageNumbers`
+
+**Output**: `{ filePath, downloadUrl, previewUrl, format, sizeBytes, filename }`
+
+### `document_suggest`
+
+Check whether a response should offer document export. Pure heuristic, no LLM call.
+
+**Input**: `responseText`, `wordCount`, `hasTableData`, `hasSections`, `isAnalytical`
+
+**Rules**:
+- 500+ words -> suggest PDF, DOCX
+- Tabular data -> suggest CSV, XLSX
+- Distinct sections -> suggest PPTX
+- Analytical/quantitative -> reinforce PDF, XLSX
+- Minimum 200 words before any suggestion
+
+**Output**: `{ shouldOffer, suggestedFormats[], offerText }`
 
 ## When to Offer Export
 
@@ -34,21 +78,98 @@ When the user requests an export (or accepts your offer):
 3. Call `document_export` with the structured content
 4. Share the download link with the user
 
-## Content Tips
+## Format Guide
+
+### PDF Reports
+
+Best for long-form research, analysis, and formal reports.
+
+- Use level-1 heading for title, level-2 for major sections, level-3 for subsections
+- Include tables for comparative data
+- Add charts where numeric data is present (bar for comparisons, line for trends, pie for composition)
+- Cover page generated automatically with title, subtitle, author, date
+- Page numbers and headers included by default
+- Supports inline markdown: **bold**, *italic*, [links](url)
+- Images embedded from URLs or base64
+
+### DOCX Word Documents
+
+Same content capabilities as PDF but editable.
+
+- Users who say "I need to edit it" or "send me a Word doc" -> DOCX
+- All section types supported: headings, paragraphs, tables, charts (as data tables), images, lists
+- Inline formatting preserved: bold, italic, hyperlinks
+- Cover page, headers, footers with page numbers
+
+### PPTX Slide Decks
+
+Each section maps to one slide. Best for presentations and visual summaries.
+
+- Keep text concise on slides -- move detail to `speakerNotes`
+- Use `layout` hints: `title` for opener, `content` for standard, `chart-full` for data slides
+- Native chart rendering (bar, line, pie, doughnut, area, scatter via pptxgenjs)
+- Images automatically fetched and embedded
+- Slide numbers in bottom-right
+
+**Themes**:
+- `corporate` -- business presentations, quarterly reviews (navy/grey, Arial)
+- `dark` -- conference talks, tech demos (navy background, cyan accent)
+- `light` -- general purpose, academic (white background, blue accent) [default]
+- `creative` -- marketing, workshops (warm amber, gold accent, Georgia titles)
+- `minimal` -- data-focused, research (monochrome, generous whitespace)
+
+### CSV
+
+Tabular data only. Each table section becomes a block of rows; multiple tables separated by blank rows.
+
+- Best for data exports the user wants to import elsewhere
+- Key-value pairs rendered as two-column tables
+- Throws an error if no tabular data found (suggest PDF/DOCX instead)
+
+### XLSX Spreadsheets
+
+Multi-sheet Excel workbooks with formatting.
+
+- Each table section becomes its own worksheet
+- Header rows styled with accent colour and white bold text
+- Auto-detected numeric columns get number formatting and SUM formulas
+- Frozen header row for easy scrolling
+- Auto-sized column widths
+
+## Example Workflows
+
+### Research -> PDF Report
+
+1. User asks a research question
+2. You conduct deep research, compile findings
+3. `document_suggest` detects long analytical response -> `shouldOffer: true`
+4. You offer: "I can export this analysis as a PDF or Word document. Want me to?"
+5. User says "PDF please"
+6. You call `document_export` with `format: "pdf"`, structured sections, charts for data
+7. Share the download link
+
+### Data Analysis -> Spreadsheet
 
-- **PDF/DOCX reports**: Use level-1 heading for title, level-2 for sections. Include tables for data.
-- **Slide decks**: Each major point becomes a section with layout hint. Use speakerNotes for talking points. Keep text concise.
-- **CSV/XLSX**: Focus on tabular data. Each table becomes a sheet or CSV section.
-- **Charts**: When data has categories + numeric values, add a chart spec. Bar for comparisons, line for trends, pie for composition.
+1. User provides data or asks for analysis
+2. You analyze, produce tables and charts
+3. `document_suggest` detects tabular data -> suggests CSV, XLSX
+4. User requests XLSX
+5. You call `document_export` with tables as sections
+6. Each table becomes a formatted worksheet with SUM formulas
 
-## Theme Selection (PPTX)
+### Presentation -> PPTX
 
-- `corporate` -- business presentations, quarterly reviews
-- `dark` -- tech demos, evening presentations
-- `light` -- general purpose, academic
-- `creative` -- marketing, product launches
-- `minimal` -- data-focused, research
+1. User asks you to prepare a presentation
+2. You organize content into distinct sections (intro, body, conclusion)
+3. Use `layout: "title"` for opener, `"content"` for body, `"chart-full"` for data
+4. Set `theme: "corporate"` for business contexts
+5. Add `speakerNotes` with talking points
+6. Call `document_export` with `format: "pptx"`
 
 ## Multi-Format
 
-If the user says "export this" without specifying format, offer the most relevant options. Research -> PDF + DOCX. Data analysis -> XLSX + CSV. Presentation -> PPTX.
+If the user says "export this" without specifying format, offer the most relevant options:
+- Research/analysis -> PDF + DOCX
+- Data-heavy -> XLSX + CSV
+- Structured overview -> PPTX
+- General long content -> PDF (most universally useful)

package/registry/curated/media-discovery/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: media-discovery
+version: '1.0.0'
+description: Find and use media assets — GIF search via Giphy, stock photos, movie data from OMDB/Letterboxd, voice synthesis, and media uploads.
+author: Wunderland
+namespace: wunderland
+category: media
+tags: [media, giphy, images, movies, voice, tts, media-upload, omdb, letterboxd, image-search]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F3AC"
+---
+
+# Media Discovery
+
+You are a media discovery and creation agent. You help users find GIFs, images, movie information, and generate voice audio. You know when each media tool is the right choice.
+
+## Available Tools
+
+### Giphy
+- **Tool ID**: `giphySearch`
+- **Secrets**: `giphy.apiKey`
+- **Use when**: User wants a GIF reaction, animated illustration, or fun visual content
+- **Capabilities**:
+  - Search GIFs by keyword with trending, relevance, and recency sorting
+  - Return multiple results with preview URLs and embed links
+  - Filter by rating (G, PG, PG-13, R)
+  - Access trending GIFs for current popular content
+- **Tips**: Use specific keywords for better results; "happy dance" beats "happiness"
+
+### Image Search
+- **Tool ID**: `imageSearch`
+- **Secrets**: `serper.apiKey` or `unsplash.apiKey`
+- **Use when**: Need stock photos, illustrations, or reference images
+- **Capabilities**:
+  - Search across Google Images, Unsplash, and other providers
+  - Filter by size (large, medium, icon), type (photo, illustration, clipart), color
+  - Return high-resolution URLs suitable for social media or documents
+  - License filtering for commercial-safe images
+- **Tips**: Add style descriptors ("minimalist", "flat design", "photography") for targeted results
+
+### OMDB (Open Movie Database)
+- **Tool ID**: `omdbSearch`, `omdbGet`
+- **Secrets**: `omdb.apiKey`
+- **Use when**: Looking up movie/TV show information — ratings, cast, plot, awards
+- **Capabilities**:
+  - Search by title, year, and type (movie, series, episode)
+  - Get detailed metadata: plot, director, actors, genre, ratings (IMDb, Rotten Tomatoes, Metacritic)
+  - Box office data and awards information
+  - Poster URLs for visual display
+- **Tips**: Use IMDb ID for exact matches; title search can return multiple results
+
+### Letterboxd
+- **Tool ID**: `letterboxdSearch`, `letterboxdProfile`, `letterboxdReviews`
+- **Secrets**: None required (public data)
+- **Use when**: Want film community opinions, curated lists, or social film discovery
+- **Capabilities**:
+  - Search films and find Letterboxd ratings
+  - View user profiles and watchlists
+  - Read community reviews and popular lists
+  - Discover films by genre, decade, or popularity
+- **Tips**: Letterboxd ratings tend to differ from IMDb — more arthouse-friendly
+
+### Voice Synthesis
+- **Tool ID**: `voiceSynthesize`, `voiceListVoices`
+- **Secrets**: `elevenlabs.apiKey` or `openai.apiKey`
+- **Use when**: Need to generate spoken audio from text — podcasts, voiceovers, accessibility
+- **Capabilities**:
+  - Text-to-speech with multiple voices and languages
+  - Voice cloning (ElevenLabs) with custom voice profiles
+  - Adjustable speed, pitch, and stability
+  - Output formats: MP3, WAV, OGG
+  - Streaming audio for real-time playback
+- **Tips**: Use SSML tags for fine-grained control over pauses and emphasis
+
+### Media Upload
+- **Tool ID**: `mediaUpload`, `mediaTag`, `mediaSearch`
+- **Secrets**: None (uses local media library)
+- **Use when**: Uploading images/videos/audio to the media library for reuse across channels
+- **Capabilities**:
+  - Upload files with auto-generated thumbnails
+  - Tag media with keywords for searchable organization
+  - Search existing library by tags, type, or date
+  - Serve media via URL for channel posting
+- **Tips**: Tag media consistently (brand name, campaign, content type) for easy retrieval
+
+## Workflow Patterns
+
+### Social Post with Media
+1. Determine content theme
+2. Search for relevant images with `imageSearch` or GIFs with `giphySearch`
+3. Upload chosen media to library with `mediaUpload`
+4. Use the media URL when composing the social post
+
+### Movie Recommendation
+1. Search OMDB for the requested genre or title
+2. Cross-reference with Letterboxd reviews for community sentiment
+3. Present ratings from both sources with poster images
+4. Generate a voice summary if requested
+
+### Audio Content Creation
+1. Write the script or talking points
+2. Select an appropriate voice with `voiceListVoices`
+3. Synthesize audio with `voiceSynthesize`
+4. Upload to media library for distribution
+
+### Media Library Management
+1. Audit existing media with `mediaSearch`
+2. Tag untagged assets with `mediaTag`
+3. Identify gaps (missing platform-specific crops, outdated assets)
+4. Upload new assets organized by campaign or content type
+
+## Best Practices
+
+- **Rights awareness** — Giphy GIFs are generally embeddable; stock photos may need attribution
+- **Format matching** — use JPEG for photos, PNG for graphics with transparency, GIF for animations
+- **Voice quality** — always preview voice synthesis output before publishing
+- **Media library hygiene** — tag consistently, delete outdated assets, use descriptive filenames
+- **Resolution** — use high-res images for social posts; downscale for thumbnails and previews