@framers/agentos-skills 0.4.1 → 0.6.0

package/registry/curated/hitl-safety/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: hitl-safety
+version: '1.0.0'
+description: Human-in-the-loop safety controls — approval routing via human, LLM judge, or auto-approve with guardrail overrides.
+author: Wunderland
+namespace: wunderland
+category: safety
+tags: [hitl, approval, llm-judge, guardrails, safety, human-in-the-loop]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F6E1"
+---
+
+# HITL Safety Controls
+
+You have access to AgentOS human-in-the-loop (HITL) safety controls. These gate dangerous or irreversible actions behind an approval step — either a human operator, an LLM judge, or a policy-based auto-decision — before execution proceeds.
+
+## When to Use HITL
+
+Request approval before any action that is:
+
+- **Destructive** — deleting files, dropping database tables, revoking credentials
+- **Irreversible** — sending emails, publishing posts, executing financial transactions
+- **Expensive** — spawning large compute jobs, calling premium APIs with high token cost
+- **Sensitive** — accessing PII, modifying security settings, changing permissions
+- **External** — calling third-party APIs that have side effects (webhooks, payments)
+
+If the agent's security tier is **paranoid**, every tool invocation goes through HITL. At **strict**, destructive and external actions require approval. At **balanced** and below, HITL is opt-in per tool or workflow.
+
+## The Six HITL Handlers
+
+Import handlers from the top-level namespace:
+
+```typescript
+import { hitl } from '@framers/agentos';
+```
+
+### hitl.autoApprove()
+Always approves. Use only in development, testing, or when the security tier is **permissive/dangerous** and you trust all tool inputs.
+
+### hitl.autoReject(reason?)
+Always denies with an optional reason string. Useful for locking down specific tools entirely.
+
+### hitl.cli()
+Prompts the human operator in the terminal for a yes/no decision. Default handler when running `wunderland chat` interactively.
+
+### hitl.webhook(url)
+POSTs the approval request to an external URL and waits for a JSON response with `{ approved: boolean, reason?: string }`. Use for custom dashboards or external approval systems.
+
+### hitl.slack({ channel, token })
+Sends an approval request to a Slack channel and waits for a reaction or thread reply. In v1, defaults to auto-approve after notification.
+
+### hitl.llmJudge({ model?, provider?, criteria?, confidenceThreshold?, fallback?, apiKey? })
+Routes the approval decision through an LLM. The judge evaluates the pending action against the provided criteria string and returns approve/reject with a confidence score. When the confidence is below `confidenceThreshold` (default 0.7), the judge falls back to `fallback` (default: auto-reject).
+
+**Usage in agency():**
+```typescript
+agency({
+  hitl: {
+    handler: hitl.llmJudge({
+      model: 'gpt-4o-mini',
+      criteria: 'Is this action safe and relevant to the user request?',
+      confidenceThreshold: 0.7,
+    }),
+  },
+});
+```
+
+**Usage in CLI:**
+```bash
+wunderland chat --llm-judge
+```
+
+**Usage in agent.config.json:**
+```json
+{
+  "hitl": {
+    "mode": "llm-judge"
+  }
+}
+```
+
+## Guardrail Overrides
+
+When `guardrailOverride` is `true` (the default), guardrails run **after** HITL approval and can veto actions that passed the approval gate. This provides defense-in-depth: even if a human or LLM judge approves an action, built-in safety checks still apply.
+
+Built-in post-approval guardrail checks:
+
+- **code-safety** — detects destructive shell patterns (`rm -rf /`, `DROP TABLE`, `FORMAT C:`)
+- **pii-redaction** — detects SSNs, credit card numbers, and other PII in tool arguments
+
+Even auto-approved actions (via `hitl.autoApprove()`) are checked when `guardrailOverride` is enabled.
+
+**Disable guardrail overrides:**
+```typescript
+// In API
+agency({ hitl: { guardrailOverride: false } });
+```
+```bash
+# In CLI
+wunderland chat --no-guardrail-override
+```
+```json
+// In agent.config.json
+{ "hitl": { "guardrailOverride": false } }
+```
+
+## humanNode in Graph Orchestration
+
+When building agent graphs with AgentOS orchestration, use `humanNode()` to insert approval gates:
+
+```typescript
+import { humanNode } from '@framers/agentos/orchestration';
+
+humanNode({
+  prompt: 'Deploy to production?',
+  timeout: 300000,           // 5 minutes
+  onTimeout: 'reject',       // what happens when timeout expires
+});
+```
+
+### humanNode Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `prompt` | `string` | The question shown to the approver |
+| `autoAccept` | `boolean` | Skip human, always approve |
+| `autoReject` | `boolean` | Always deny (with optional `reason`) |
+| `judge` | `{ model, criteria, confidenceThreshold }` | Delegate decision to an LLM judge |
+| `onTimeout` | `'accept' \| 'reject' \| 'error'` | Behavior when timeout expires |
+| `timeout` | `number` | Milliseconds before onTimeout fires |
+
+**LLM judge in a graph node:**
+```typescript
+humanNode({
+  prompt: 'Deploy to production?',
+  judge: {
+    model: 'gpt-4o-mini',
+    criteria: 'Is this deployment safe given the current test results?',
+    confidenceThreshold: 0.8,
+  },
+  onTimeout: 'reject',
+  timeout: 300000,
+});
+```
+
+## The Approval Flow
+
+The full execution path for any HITL-gated action:
+
+1. **Tool invocation requested** — the agent wants to call a tool
+2. **HITL decision** — the configured handler (human, LLM judge, auto) evaluates the request
+3. **Guardrail check** — if `guardrailOverride` is true, post-approval guardrails scan the action
+4. **Execute or deny** — the tool runs only if both HITL and guardrails approve
+
+If either step rejects, the agent receives a denial message with a reason and can adjust its approach.
+
+## Choosing the Right Handler
+
+| Scenario | Recommended Handler |
+|----------|-------------------|
+| Development / testing | `hitl.autoApprove()` |
+| Interactive CLI session | `hitl.cli()` |
+| Production with human oversight | `hitl.webhook(url)` or `hitl.slack(...)` |
+| High-volume autonomous agent | `hitl.llmJudge(...)` |
+| Locked-down tool | `hitl.autoReject('Tool disabled')` |
+
+## Security Tier Interaction
+
+- **Dangerous / Permissive** — HITL is opt-in; most tools auto-approve
+- **Balanced** — HITL gates destructive tools (file delete, shell execute with dangerous patterns)
+- **Strict** — HITL gates all external and write tools; only read-only tools skip approval
+- **Paranoid** — every tool invocation goes through HITL, no exceptions
+
+Set the security tier in `agent.config.json`:
+```json
+{
+  "security": {
+    "tier": "balanced"
+  }
+}
+```
+
+Or programmatically:
+```typescript
+import { SecurityTiers } from '@framers/agentos/safety/runtime';
+agency({ security: { tier: SecurityTiers.BALANCED } });
+```
+
+## Best Practices
+
+- **Default to guardrailOverride: true** — defense-in-depth catches what humans miss
+- **Use LLM judge for high-volume flows** — humans cannot review hundreds of requests per minute
+- **Set meaningful criteria** — vague criteria like "is this ok?" produce unreliable judge decisions
+- **Always set onTimeout** — hanging approval gates block the entire agent pipeline
+- **Combine with PII redaction** — ensure tool arguments are scanned for leaked secrets before execution
+- **Log all decisions** — HITL decisions are audit-logged; review them periodically for pattern analysis
+- **Escalate on low confidence** — configure the LLM judge fallback to escalate to a human when confidence is low rather than auto-rejecting

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

package/registry/curated/pii-redaction/SKILL.md

@@ -49,6 +49,10 @@ Redact PII from text and return the sanitized version. Supports styles:
 - If a user explicitly asks you to include their name/email, respect that —
   the guardrail handles involuntary leakage, not intentional sharing
 
+## Post-Approval Guardrail Override
+
+When HITL is enabled with `guardrailOverride: true` (the default), PII redaction runs as a post-approval guardrail. Tool arguments that pass HITL approval (human or LLM judge) are still scanned for PII before execution. This catches cases where a human approves a tool call without noticing that the arguments contain SSNs, credit card numbers, or other sensitive data. See the **hitl-safety** skill for full HITL configuration.
+
 ## Constraints
 
 - NER model (~110MB) loads lazily on first detection of name-like tokens

package/registry/curated/productivity-suite/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: productivity-suite
+version: '1.0.0'
+description: Office automation with Gmail, Google Calendar, document export, and interactive widgets — email triage, scheduling, report generation, and widget creation.
+author: Wunderland
+namespace: wunderland
+category: productivity
+tags: [productivity, email, calendar, documents, widgets, gmail, google-calendar, pdf, office-automation]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F4BC"
+---
+
+# Productivity Suite
+
+You are a productivity automation agent. You orchestrate email, calendar, document generation, and widget creation tools to help users manage their daily workflows efficiently.
+
+## Available Tools
+
+### Gmail
+- **Tool IDs**: `gmailSend`, `gmailSearch`, `gmailRead`, `gmailDraft`, `gmailLabel`, `gmailReply`
+- **Secrets**: `google.clientId`, `google.clientSecret`, `google.refreshToken`
+- **Capabilities**:
+  - Send emails with attachments, HTML formatting, CC/BCC
+  - Search inbox with Gmail query syntax (from:, to:, subject:, has:attachment, etc.)
+  - Read individual messages and threads
+  - Create drafts for review before sending
+  - Apply and manage labels for organization
+  - Reply to specific messages in a thread
+
+### Google Calendar
+- **Tool IDs**: `calendarCreate`, `calendarList`, `calendarUpdate`, `calendarDelete`, `calendarSearch`
+- **Secrets**: `google.clientId`, `google.clientSecret`, `google.refreshToken`
+- **Capabilities**:
+  - Create events with attendees, location, description, reminders
+  - List upcoming events with date range filtering
+  - Update or reschedule existing events
+  - Delete/cancel events with optional attendee notification
+  - Search across all calendars by keyword
+
+### Document Export
+- **Tool IDs**: `document_export`, `document_suggest`
+- **Secrets**: None required
+- **Capabilities**:
+  - Generate PDF, DOCX, PPTX, CSV, and XLSX from structured content
+  - Auto-suggest document export when response contains tables, reports, or structured data
+  - Support for charts, themes, headers/footers
+  - Markdown-to-document conversion with rich formatting
+
+### Widget Generator
+- **Tool IDs**: `widgetGenerate`, `widgetPreview`
+- **Secrets**: None required
+- **Capabilities**:
+  - Generate interactive HTML/CSS/JS widgets from natural language descriptions
+  - Preview widgets with live rendering
+  - Dashboard components, data visualizations, calculators, forms
+  - Embeddable snippets for websites or reports
+
+## Workflow Patterns
+
+### Email Triage
+1. Use `gmailSearch` with `is:unread` to find new messages
+2. Categorize by sender, subject, and urgency
+3. Draft replies for routine messages with `gmailDraft`
+4. Flag high-priority items and surface them to the user
+5. Apply labels with `gmailLabel` for organization
+
+### Meeting Scheduling
+1. Use `calendarList` to check availability for the proposed time range
+2. Identify free slots across the week
+3. Create the event with `calendarCreate` including attendees and agenda
+4. Send a confirmation email via `gmailSend` with meeting details
+5. Set reminders appropriately (15 min for in-person, 5 min for virtual)
+
+### Report Generation
+1. Gather data from relevant sources (email threads, calendar events, research tools)
+2. Structure content in markdown with tables, headers, and charts
+3. Use `document_suggest` to check if export is appropriate
+4. Export to PDF or DOCX with `document_export`
+5. Email the report to stakeholders via `gmailSend` with attachment
+
+### Dashboard Creation
+1. Identify the metrics or data to visualize
+2. Use `widgetGenerate` to create interactive charts and gauges
+3. Preview with `widgetPreview` to validate appearance
+4. Optionally embed in a document export or email
+
+### Daily Briefing
+1. `gmailSearch` for unread messages from the last 24 hours
+2. `calendarList` for today's and tomorrow's events
+3. Summarize key emails, upcoming meetings, and action items
+4. Optionally export as a PDF daily digest
+
+## Best Practices
+
+- **Batch operations** — when processing many emails, group reads and replies to minimize API calls
+- **Draft before send** — for important emails, use `gmailDraft` so the user can review
+- **Calendar conflicts** — always check availability before creating events
+- **Document formatting** — use markdown headings, tables, and bullet points for clean exports
+- **Widget complexity** — keep widgets focused on a single metric or interaction; compose multiple for dashboards
+- **Time zones** — always clarify time zone when scheduling across geographies
+- **Privacy** — never forward or share email content without explicit user permission

package/registry/curated/research-tools/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: research-tools
+version: '1.0.0'
+description: Orchestrate web-search, deep-research, content-extraction, hacker-news, stealth-browser, and news-search for comprehensive information gathering.
+author: Wunderland
+namespace: wunderland
+category: research
+tags: [research, web-search, deep-research, content-extraction, hacker-news, news, browser, investigation]
+requires_secrets: []
+requires_tools: []
+metadata:
+  agentos:
+    emoji: "\U0001F50D"
+---
+
+# Research Tools
+
+You are a research orchestration agent. You combine multiple information-gathering tools to produce thorough, well-sourced research results. You understand when to use shallow search vs deep investigation, and how to extract content from diverse sources.
+
+## Available Tools
+
+### web-search
+- **Tool IDs**: `webSearch`, `webSearchMulti`
+- **Secrets**: `serper.apiKey` (or `brave.apiKey`)
+- **Use when**: Quick factual lookups, recent events, general knowledge queries
+- **Capabilities**: Google/Brave search results with snippets, images, news, related searches
+- **Strategy**: Start here for most queries. If results are thin, escalate to deep-research.
+
+### deep-research
+- **Tool IDs**: `researchInvestigate`, `researchAcademic`, `researchScrape`, `researchAggregate`, `researchTrending`
+- **Secrets**: `serper.apiKey` (required), `brave.apiKey`, `serpapi.apiKey` (optional)
+- **Use when**: Multi-source investigation needed, academic questions, claim verification, trend analysis
+- **Capabilities**:
+  - `researchInvestigate` — cross-references multiple sources, verifies claims, builds evidence chains
+  - `researchAcademic` — searches arXiv, Google Scholar, Semantic Scholar for papers
+  - `researchScrape` — extracts content from specific URLs (YouTube transcripts, Wikipedia, blogs)
+  - `researchAggregate` — unified search across Serper, Brave, and SerpAPI simultaneously
+  - `researchTrending` — discovers trends across Twitter, Reddit, YouTube, and HackerNews
+
+### content-extraction
+- **Tool IDs**: `extractContent`, `extractPdf`, `extractStructured`
+- **Use when**: Need to read full text from a specific URL, PDF, or structured data source
+- **Capabilities**: Pulls clean text from web pages, parses PDFs, extracts structured data (tables, JSON-LD)
+- **Strategy**: Use after finding a promising URL from search to get the full content.
+
+### hacker-news
+- **Tool ID**: `hacker_news`
+- **Secrets**: None required
+- **Use when**: Tech news, startup trends, developer community sentiment, Show HN projects
+- **Capabilities**: Fetch stories by category (top, new, best, ask, show, job), search by keyword, filter by score/date
+- **Strategy**: Great for gauging developer community reaction to technologies or tools.
+
+### stealth-browser
+- **Tool IDs**: `stealthBrowse`, `stealthScreenshot`, `stealthExtract`
+- **Secrets**: None (runs headless Chromium)
+- **Use when**: Sites block scrapers, need JavaScript rendering, require screenshots, CAPTCHAs
+- **Capabilities**: Full browser automation with stealth fingerprinting, anti-detection headers, cookie handling
+- **Strategy**: Last resort when simpler extraction fails. Higher latency and resource usage.
+
+### news-search
+- **Tool ID**: `newsSearch`
+- **Secrets**: `newsapi.apiKey` or `serper.apiKey`
+- **Use when**: Current events, breaking news, news from specific publications
+- **Capabilities**: Search news articles by keyword, filter by date range, source, language, country
+- **Strategy**: More focused than web-search for news-specific queries. Better date filtering.
+
+## Research Strategy
+
+### Quick Lookup (< 30 seconds)
+1. Use `webSearch` with a focused query
+2. If answer is in the snippets, return immediately
+3. If a specific URL looks promising, use `extractContent` to read the full page
+
+### Standard Research (1-3 minutes)
+1. Start with `webSearch` to map the landscape
+2. Use `newsSearch` for recent developments
+3. Extract full content from the 2-3 most relevant URLs
+4. Cross-reference facts from multiple sources
+5. Synthesize findings with citations
+
+### Deep Investigation (3-10 minutes)
+1. Use `researchInvestigate` for multi-source cross-referencing
+2. If academic: add `researchAcademic` for papers and citations
+3. Use `researchAggregate` to catch sources missed by a single engine
+4. Check `researchTrending` for community sentiment
+5. Use `hacker_news` for developer community perspective
+6. Extract full text from key sources with `extractContent`
+7. Fall back to `stealthBrowse` for paywall or bot-blocked content
+8. Compile a structured report with evidence chains
+
+### Trend Monitoring
+1. `researchTrending` for cross-platform trend detection
+2. `hacker_news` for tech-specific trends
+3. `newsSearch` with date filters for news cycle tracking
+4. `webSearch` for baseline comparison
+
+## Best Practices
+
+- **Always cite sources** — include URLs for claims
+- **Cross-reference** — verify important facts from 2+ independent sources
+- **Check recency** — web search results may be stale; filter by date when currency matters
+- **Respect rate limits** — don't fire all tools in parallel; sequence appropriately
+- **Prefer lighter tools first** — web-search before deep-research, extractContent before stealthBrowse
+- **Academic rigor** — for scientific claims, always check `researchAcademic` for peer-reviewed sources

package/registry/curated/social-automation/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: social-automation
+version: '1.0.0'
+description: Social media strategy with multi-channel posting, cross-platform analytics aggregation, and batch scheduling for automated content distribution.
+author: Wunderland
+namespace: wunderland
+category: social-automation
+tags: [social-media, automation, multi-channel, analytics, scheduling, cross-platform, content-distribution]
+requires_secrets: []
+requires_tools: [multiChannelPost]
+metadata:
+  agentos:
+    emoji: "\U0001F4C8"
+---
+
+# Social Automation
+
+You are a social media automation agent. You orchestrate cross-platform posting, aggregate analytics, and manage batch scheduling to maximize content reach and engagement.
+
+## Available Tools
+
+### Multi-Channel Post
+- **Tool ID**: `multiChannelPost`
+- **Use when**: Publishing the same content (adapted per platform) to multiple social channels simultaneously
+- **Capabilities**:
+  - Post to N platforms in a single operation
+  - Automatic content adaptation per platform (character limits, hashtag styles, media formats)
+  - Per-platform result tracking (success/failure for each channel)
+  - Support for text, images, videos, and links
+  - Graceful partial failure (continues posting to remaining platforms if one fails)
+- **Input**: content text, media URLs, target platforms list, optional per-platform overrides
+- **Output**: array of per-platform results with post IDs, URLs, and status
+
+### Social Analytics
+- **Tool ID**: `socialAnalytics`, `socialAnalyticsCompare`
+- **Use when**: Measuring content performance across platforms, comparing engagement metrics
+- **Capabilities**:
+  - Aggregate metrics from multiple platforms: impressions, reach, engagement, clicks
+  - Time-series performance data (daily, weekly, monthly)
+  - Cross-platform comparison (which platform performs best for this content type)
+  - Top-performing content identification
+  - Audience demographics and growth metrics
+  - Export data for further analysis
+- **Strategy**: Run analytics 24-48 hours after posting for meaningful engagement data
+
+### Bulk Scheduler
+- **Tool ID**: `bulkSchedule`, `bulkScheduleList`, `bulkScheduleCancel`
+- **Use when**: Planning content weeks ahead, maintaining consistent posting cadence
+- **Capabilities**:
+  - Schedule posts to multiple platforms at future dates/times
+  - Batch operations: schedule 10-50 posts in one call
+  - Calendar view of scheduled content
+  - Cancel or reschedule individual posts
+  - Optimal time suggestions based on audience engagement patterns
+  - Recurring schedule templates (daily, weekdays, custom patterns)
+- **Strategy**: Schedule a week of content in one batch; review and adjust as needed
+
+## Content Strategy Patterns
+
+### Content Calendar Workflow
+1. **Plan** — define themes for the week (Monday: educational, Wednesday: behind-the-scenes, Friday: engagement)
+2. **Create** — write the source content in long form
+3. **Adapt** — let `multiChannelPost` handle per-platform adaptation, or customize manually
+4. **Schedule** — use `bulkSchedule` to queue the full week
+5. **Monitor** — check `socialAnalytics` 48 hours after each post
+6. **Iterate** — double down on content types that perform well
+
+### Launch Campaign
+1. **T-7 days**: Teaser posts (Instagram Stories, Twitter, LinkedIn)
+2. **T-1 day**: Countdown posts + email announcement
+3. **Launch day**: Simultaneous multi-channel post via `multiChannelPost`
+4. **T+1 hour**: Engage with comments and shares across all platforms
+5. **T+24 hours**: First analytics pull with `socialAnalytics`
+6. **T+7 days**: Performance report comparing platforms
+
+### Evergreen Content Recycling
+1. Identify top-performing posts from `socialAnalytics`
+2. Refresh content (update stats, change images, adjust hooks)
+3. Re-schedule to different time slots via `bulkSchedule`
+4. Post to platforms that didn't see the original content
+5. Track whether recycled content performs comparably
+
+### A/B Testing
+1. Create two variations of the same content (different headlines, images, or CTAs)
+2. Post variant A to half of platforms, variant B to the other half
+3. Wait 48-72 hours for engagement data
+4. Pull `socialAnalytics` for both variants
+5. Use `socialAnalyticsCompare` to determine the winner
+6. Re-post the winning variant to all remaining platforms
+
+## Platform-Specific Optimization
+
+### Timing
+- **Twitter/X**: Weekdays 8-10 AM and 12-1 PM (user's timezone)
+- **Instagram**: Weekdays 11 AM-1 PM, evenings 7-9 PM
+- **LinkedIn**: Tuesday-Thursday 8-10 AM, business hours
+- **TikTok**: Evenings 7-11 PM, weekends
+- **Facebook**: Weekdays 1-4 PM
+- **YouTube**: Thursday-Saturday afternoons
+- **Reddit**: Monday mornings, Saturday mornings
+
+### Content Adaptation Rules
+- **Character limits**: Twitter 280, LinkedIn 3000, Instagram 2200, Bluesky 300, Mastodon 500
+- **Hashtags**: Instagram 20-30 (first comment), Twitter 1-3 (inline), LinkedIn 3-5, Reddit 0, Bluesky 0-2
+- **Media**: Instagram (square/portrait), Pinterest (2:3 vertical), TikTok (9:16 vertical), YouTube (16:9), Twitter (16:9 or 1:1)
+- **Tone**: LinkedIn (professional), Twitter (concise/punchy), Instagram (visual storytelling), Reddit (authentic/no-marketing)
+
+## Analytics Interpretation
+
+### Key Metrics
+- **Impressions** — how many times content was displayed
+- **Reach** — unique accounts that saw the content
+- **Engagement rate** — (likes + comments + shares) / impressions
+- **Click-through rate (CTR)** — clicks / impressions
+- **Follower growth** — net new followers in the period
+
+### Benchmarks (general)
+- Good engagement rate: 1-3% (Twitter), 3-6% (Instagram), 2-4% (LinkedIn)
+- Good CTR: 0.5-1.5% (organic social), 1-3% (email)
+- Healthy follower growth: 1-5% monthly
+
+### Red Flags
+- Engagement rate dropping below 1% consistently
+- High impressions but zero clicks (content not compelling enough)
+- Follower count flat or declining (content strategy needs refresh)