Update to viral.app

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,47 +1,80 @@
 ---
 name: viral-app-mcp
-description: Work with viral.app through its MCP server. Use when the user asks about viral.app data or workflows, social media analytics for tracked accounts and videos, UGC or creator campaign performance, tag workflows, or live TikTok/Instagram/YouTube/Facebook lookups. Covers connecting the server, OAuth vs API-key auth, the credit quote-then-confirm flow, and picking the right tool group.
+description: Core guide to the viral.app MCP server (UGC and creator-marketing analytics for TikTok, Instagram, YouTube, Facebook and Snapchat, plus the Creator Hub). Use whenever a task touches viral.app data or actions, to connect and authenticate the server, pick among its 100+ tools, follow the credit quote-then-confirm flow, get ids, units and date formats right, know what MCP cannot do, and load the specialized skill for the job (ugc-reporting, creator-campaigns, viral-research, ugc-automations). Not needed for general social-media advice that uses no viral.app data.
 ---
 
 # viral.app MCP
 
-viral.app tracks and analyzes UGC performance across TikTok, Instagram, YouTube, and Facebook. Its MCP server exposes 50+ tools built on the same API procedures as the public REST API, so organization scoping, permissions, rate limits, and plan checks match normal API behavior.
+viral.app tracks UGC performance across TikTok, Instagram, YouTube, Facebook and Snapchat and runs creator programs (campaigns, briefs, job postings, applications, chat, payouts). Its MCP server exposes 100+ tools built on the same procedures as the public API, so organization scoping, roles, rate limits and plan checks match the API.
 
-- MCP endpoint: `https://viral.app/api/mcp` (streamable HTTP)
-- Setup hub: https://viral.app/app/org/api/agents
-- Full API reference: https://viral.app/api/v1/docs
-- Authorized-client review/revocation: https://viral.app/app/user/settings/security
+- Endpoint: `https://viral.app/api/mcp` (streamable HTTP)
+- Setup and API keys: https://viral.app/app/org/api/agents
+- API reference: https://viral.app/api/v1/docs
+- Review or revoke authorized clients: https://viral.app/app/user/settings/security
+- The server also serves this guidance as the resource `mcp://viral.app/docs`; `search_content` and `read_content` search the viral.app docs.
 
-## Connecting and auth
+## Pick the skill
 
-If this plugin's MCP server (`viral_app`) is not yet authenticated, the user completes a browser OAuth flow (in Claude Code: `/mcp`, select `viral_app`, authenticate). During consent they pick ONE organization; the grant is permanently scoped to it.
+| The user wants to | Load |
+| --- | --- |
+| Know how content, accounts, creators or campaigns performed; a weekly or monthly report; a recurring report | `ugc-reporting` |
+| Write a brief, create or change a campaign, assign creators, post a job, answer applications, chat with creators, check payouts | `creator-campaigns` |
+| Find what works in a niche, hooks, formats, similar videos, analyze a video's content | `viral-research` |
+| Be alerted or have the agent act when something happens (new application, message, payout due, milestone); MCP Events (`events/list`) | `ugc-automations` |
 
-Rules:
+## Connect and authenticate
 
-- Default to OAuth. Do NOT ask the user for an API key or add an `x-api-key` header unless they explicitly need one agent to switch between multiple viral.app organizations. API keys are created per organization at Settings -> API Keys and carry that organization's scope.
-- If a call fails with an authorization error, the grant may have been revoked or the user removed from the organization; re-authenticate rather than retrying.
+- OAuth is the default. The user signs in in the browser and picks ONE organization; the grant stays scoped to it. In Claude Code: `/mcp`, select `viral_app`, authenticate. In Codex: `codex mcp login viral_app`.
+- Do not ask for an API key or add an `x-api-key` header unless the user needs one agent to switch between several organizations. API keys are created per organization at https://viral.app/app/org/api/keys and carry that organization's scope.
+- MCP needs a plan with API access. `UNAUTHORIZED` means the grant was revoked or the membership ended: re-authenticate, do not retry. `FORBIDDEN` names the missing role, scope or plan feature: tell the user.
 
-## Tool groups: pick the right one
+## Rules for every tool
 
-- **Tracking** (`list_tracked_accounts`, `add_tracked_accounts`, `list_tracked_videos`, `get_tracking_status`, `refresh_*`): manage what viral.app follows over time. Adding an account or video starts background sync; cadence depends on the organization's plan.
-- **Analytics** (`list_accounts`, `get_account_history`, `list_videos`, `get_video_history`, `get_analytics_kpis`, `get_top_*`): read the tracked historical dataset. This is the core workflow: track first, then query history.
-- **Tags and workflows** (`list_tags`, `create_tag_workflow`, `add_video_tags`, `preview_tag_workflow`, ...): organization tags, account-level tag rules, tag workflows, and video tag assignments.
-- **Live lookups** (`live_get_account`, `live_get_video`, `live_search_*`): fetch fresh platform data right now. Live results do NOT add anything to tracking and build no history. Use for just-in-time checks like "how many views does this video have right now?".
-- **Creator Hub** (`list_creators`, `list_campaigns`, `list_projects`): campaign and creator management reads.
+- **Track first, then analyze.** Tracking tools add accounts and videos, analytics tools read their history, `live_*` tools fetch current platform data without tracking it.
+- **Credits: quote, then confirm.** Live lookups (`live_*`), refreshes (`refresh_*`) and `analyze_video` spend credits. Call without `confirm` first: nothing is spent and you get `estimated_credits` and `credits_remaining`. Show the quote, get explicit approval, then call again with the same arguments plus `confirm: true`. Never send `confirm: true` first. On `RATE_LIMITED`, stop and tell the user.
+- **Anything that reaches people needs informed approval.** Tools that email, message or notify creators (`create_creator` with invite, `invite_creator`, `send_chat_message`, `reply_to_application`, `assign_creators_to_campaign`, brief writes with `notify: true`) are marked open-world: state the recipients and the exact text before calling. Set `notify: true` only when the user asked to notify.
+- **Campaign writes need a preview.** Run `preview_campaign`, show its sentences and warnings, then pass its `previewHash` to `create_campaign` or `update_campaign`. Without it the call fails with `PREVIEW_REQUIRED`.
+- **Content is markdown.** Briefs take `contentMarkdown`, job postings `bodyMarkdown` and `challengeBriefMarkdown`. Show the full draft before writing.
+- **Jobs start as drafts.** `create_job` never publishes; `set_job_status` with `"public"` does, only after the user agrees.
+- **Tracking is asynchronous.** After `add_tracked_accounts` or `add_tracked_videos`, data arrives over the next minutes. Do not poll in a loop; say it is syncing.
+- **Read before replace.** `update_job`, `update_creator_accounts` and a brief's `sampleVideos` replace the whole value: read first (`get_job`, `get_creator`, `get_brief`) and send everything to keep.
 
-## Credits: quote then confirm
+## Ids, units and dates
 
-Live lookups and refresh tools spend viral.app credits and use a two-step protocol:
+- Organization account ids start with `orgacc_` (not platform ids), projects `orgproj_`, creators `orgcre_`, campaigns `orgcamp_`, briefs `orgbrief_`, jobs `orgjob_`, applications `orgjapp_`, library videos `orgrsv_`, chat threads `crchat_`, tags `orgtag_`/`systag_`.
+- Platforms are lowercase: `tiktok`, `instagram`, `youtube`, `facebook`, `snapchat`.
+- Date ranges are ISO `YYYY-MM-DD` (`{ from, to }`).
+- Tag filters take tag ids from `list_tags` or `resolve_tags`. Names are silently ignored and the result comes back unfiltered.
+- Money: campaign specs use major units (10 = 10.00). Job amounts, `list_due_payouts` and `list_upcoming_payouts` use minor units (divide by 10^precision). `list_paid_payouts` uses major units.
+- Ranking: plain metrics (`viewCount`) rank lifetime totals; for "this week" or "last 30 days" rank by the `*InPeriod` metric.
 
-1. Call the tool WITHOUT `confirm` first. It spends nothing and returns `confirm_required`, `estimated_credits`, and `credits_remaining`.
-2. Show the user the quote and get their explicit approval.
-3. Call the same tool again with `confirm: true` to execute. The result includes a credit receipt.
+## Showing results
 
-Never pass `confirm: true` on the first call. Credit spends are rate limited per organization; if the limit trips, stop and tell the user instead of retrying.
+In clients that render MCP Apps (Claude web, Desktop and mobile, ChatGPT), present results with `show`, using data you already fetched. It fetches nothing, changes nothing and costs no credits. One card per call; never invent or round numbers; once a card is shown, add the insight instead of repeating its numbers. In terminal clients (Claude Code, Codex CLI) `show` only returns the same data as markdown, so answer with text and tables there.
 
-## Data model notes
+`show` takes one flat object: `card`, an optional `title`, and the one field named for the card.
 
-- Organization account IDs are prefixed `orgacc_`; they are NOT platform account IDs. Project IDs are prefixed `orgproj_`.
-- Platform values are lowercase: `tiktok`, `instagram`, `youtube`, `facebook`.
-- Date ranges use ISO `YYYY-MM-DD`.
-- Use MCP tool discovery for exact input schemas; the server also exposes an `mcp://viral.app/docs` resource with the same guidance.
+| `card` | Field | Content |
+| --- | --- | --- |
+| `videos` / `video` | `videos` (1 to 12) / `video` | `platform`, `platformVideoId` plus metrics copied from `get_top_videos`, `list_videos` or `search_viral_video_library`; `tracked: true` for the organization's own videos, `id` (`orgrsv_`) for library videos |
+| `account` | `account` | `platform` plus `username` or `platformAccountId`, and metrics (camelCase) |
+| `creators` / `creator` | `creators` (1 to 24) / `creator` | `id`, `name`, `status`, `campaignName`, `accounts`, metrics |
+| `campaign`, `job`, `brief` | same name | `{ "id": "orgcamp_…" }` (or `orgjob_`, `orgbrief_`) only; the card loads the rest |
+| `kpis` | `kpis` | `tiles: [{ label, value, previousValue, format, currency, higherIsBetter }]`, `period`, `previousPeriod`; `previousValue` comes from the KPI tool's `previous` block |
+| `chart-area`, `chart-bar`, `chart-pie` | `chart` | `xKey`, `series: [{ key, name }]`, `data` rows; pie: exactly one series and 2 to 12 rows |
+
+```json
+{ "card": "campaign", "title": "Fall launch", "campaign": { "id": "orgcamp_RwmraAffhMt9" } }
+```
+
+More examples per card: `references/cards.md`.
+
+`open_viral_app_home` and `open_chat_cards` are ChatGPT UI entrypoints (the sidebar app and the conversation panel). Never call them yourself.
+
+## Not available over MCP
+
+Jobs Discovery (matching creators to jobs), starting or initiating payouts, canceling or reinstating payouts, deleting tracked accounts, and ad boosts. Point the user to the viral.app dashboard for these.
+
+## Tool map
+
+`references/tools.md` lists every tool by group with a one-line purpose. Use MCP tool discovery for exact input schemas.